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Preface 


Document Objectives 


The VAX-11 SORT/MERGE User’s Guide describes how to use the 
SORT/MERGE utility of the VAX/VMS Operating System, Version 3. 


Intended Audience 


This manual is intended for users familiar with VAX/VMS. VAX-11 
SORT/MERGE takes two forms: a utility invoked by a command line anda 
package of subroutines callable from a user program. Chapters 1 and 2, 
which describe the utility, are written so that users with little or no 
programming experience can understand how to use the SORT/MERGE 
utility. Chapter 3, which describes the callable subroutines, is written for 
programmers experienced with one or more VAX-11 native mode 
languages. 


Document Structure 


Chapter 1 introduces the SORT/MERGE utility and shows how to execute 
a simple sort or merge operation. 


Chapter 2 describes all qualifiers, subqualifiers, and parameters that can 
be used with the SORT/MERGE utility. 


Chapter 3 explains how to call SORT and MERGE subroutines from a user 
program. 


Chapter 4 provides ways to improve SORT efficiency. 
Appendix A lists SORT/MERGE error messages with recovery procedures. 


Appendixes B, C, and D contain the following programming aids: 
octal /hexadecimal/decimal conversion charts, ASCII character set, and 
data types used by VAX-11 SORT/MERGE. 


The Glossary defines terms used in the manual. 


Finally, page references to key terms appear in the index. 


VIL 


Associated Documents 


Familiarity with the following documents is helpful: 
VAX/VMS Primer 
VAX/VMS Command Language User’s Guide 


Introduction to VAX-11 Record Management Services 


For programmers who use a VAX-11 native mode language, such as 
VAX-11 FORTRAN, the related language manual provides necessary 


information. 


For a complete list of all VAX-11 documents, including brief descriptions of 
each, see the VAX~—11 Information Directory. 


Conventions 


This manual uses the following conventions: 


$ 


red print 


ULL 


The dollar sign is the system prompt. It indicates that the 
VAX/VMS command interpreter is ready for command 
input. Also, the $ must appear in the first character position 
of a command in an indirect command procedure. 


The return represents a carriage return/line feed. Pressing 
this key after entering a full command line ends the 
command input and begins processing. 


Square brackets indicate the enclosed portion is optional. 


Braces indicate options where you must select one in the 
vertical list. 


The n indicates variable data input (typically some number 
value). 


Underscore indicates an entered underscore character. 


The circumflex represents a control character. For example, 
*C represents pressing the keyboard “Control” character and 
the letter C at the same time. 


Indicates characters you type at the terminal. All characters 
the system prints or displays are in black. 


9 


c 


Chapter 1 
Getting Started 


Most organizations keep records. As changes occur, they must rearrange 
these records or combine several information files. Organizations as differ- 
ent as banks, research laboratories, schools, and hospitals share the need 
for a fast and simple means of arranging their records and printing, 
processing, or storing the reordered information. VAX-11 SORT/MERGE 
provides a fast and easy way to sort and merge records stored on any 
VAX/VMS device. 


This chapter: 
e Introduces the VAX-11 SORT and MERGE utilities 


e Shows the syntax required for simple sort and merge operations and gives 
examples 


¢ Mentions circumstances in which you need additional qualifiers 


© Describes the procedure for running batch SORT and MERGE 


You can run SORT or MERGE interactively at a terminal, as a batch job, or 
as part of a program you write. Section 1.1 discusses executing a simple 
sort at a terminal; Section 1.2 does the same for a merge. Batch jobs are 
described in Section 1.3. Chapter 2 gives a full explanation of interactive 
sorting and merging and describes all qualifiers. Chapter 3 explains how to 
call SORT or MERGE from a user program. 


1.1 Sorting Records 


VAX-11 SORT takes records from one or more input files (up to 10), sorts 
them according to the key field(s) you specify, and generates one reordered 
output file. 


1-2 


For example, the following list represents a file of records indicating tem- 
perature and humidity level at 2:00 p.m. for one week. Each record contains 
three fields: date, temperature, and humidity level. 


Date Temp Humidity 
9-15-80 735 bees) 
9-16-80 68 30 
9-17-80 70 90 
9-18-80 78 60 
9-19-86 B3 30 
9-20-80 BO 70 
9-21-80 85 BQ 


You can create a new file that contains the same records in order from low 
to high temperature by specifying the temperature field as the key field in 
your sort. After sorting, the new file looks like this: 


Date Temp Humidity 
9-16-80 68 90 
9-17-80 70 90 
9-15-80 735 35 
9-18-80 78 60 
9-20-80 BO 709 
9-19-80 83 50 
9-21-86 85 80 


You run SORT at a terminal by using the SORT command line. Suppose 
you have a file of sales records like the ones below, with the name 
SALES.DAT. Each record contains six fields: date of sale, department code, 
salesperson, account number, customer name, and amount of sale. The 
number ranges below the list of records indicate the position and size of 
each information field within the record. 


Date Dpt Salesp Acct Cust-Name Amt 
091580 25 Fielding 980342 Coolidge Carol 24999 
O91580 25 Sanchez G43881 McKee Michael 2499 
091580 25 Bradley 733735 Rice Anne 10875 
091580 19 Arndt 166392 Wilson Brent 1298 
O91580 28 Meredith 272731 Karsten Jane 4000 
091580 25 Bradley 829582 Olsen Allen 3350 
O91580 19 Erkkila 980342 Coolidge Carol 7200 
Ce th ee ees ee a] 

1-7 8-10 11-21 22-28 29-58 59-65 


You want to rearrange the sales records so that they are in alphabetical 
order by customer name. The information field containing customer name 
is the key field, or “key,” for your sort. As part of the SORT command, you 
must specify (1) the initial position of the key field in each record and 
(2) the length of the key field. You must also provide the names of (1) the 
file you want to sort and (2) the sorted file you create. You name the new 
file BILLING.LIS. The command you type at the terminal is: 


¢SORT/KEY=(POSITION=29,SIZE=30) SALES.DAT BILLING.LIS RED) 
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SORT also accepts abbreviated command lines such as: 


$ SORT /K=(PO=29+SI1=30) SALES.DAT BILLING.LIS ‘er 


You can now display or print the new file of sorted records by using the 
TYPE or PRINT command. 


@ TYPE BILLING.LIS fer 


091580 19 Erkkila 980342 Coolidge Carol 7200 
091580 25 Fielding 980342 Coolidge Carol 24999 
091580 28 Meredith 272731 Karsten Jane 4000 
091580 25 Sanchez 643881 McKee Michael 2499 
091580 25 Bradley 829582 Olsen Allen 3350 
091580 25 Bradley 733735 Rice Anne 10875 
091580 19 Arndt 166392 Wilson Brent 1298 


1.1.1 The SORT Command 


The SORT command has three parts, separated by spaces. 


0) @ 
a a eae | 


SORT{qualifiers] input-file-specification| qualifier] 


output-file-specification| qualifiers] 
ae nee ee 


@ 


1. Command name (SORT) 


SORT is the command name that invokes the VAX-11 SORT utility. 
Command name qualifiers describe the key(s) and specify sort options 
such as sorting process and number of work files. Use a slash (/) before 
any qualifiers that follow SORT. Of the eight qualifiers SORT accepts, 
/KEY is the only mandatory one. 


The SORT command needs two parameters: 


e The name of the file to be sorted (the input file) 


e The name you give the new, reordered file (the output file) 


2. Input file parameter 


This parameter specifies the file or files you want to sort. You can sort 
up to 10 input files into one output file. 


3. Output file parameter 


This parameter specifies the sorted file you want to create. Its qualifiers 
can request characteristics for the sorted output file. Specify only one 
output file. 
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1.1.2 SORT Qualifiers 


Eight SORT qualifiers are available. You must always specify the /KEY 
qualifier. /KEY accepts several subqualifiers following an equals sign. You 
list these inside parentheses and separate them by commas. The SORT 
command for the sales records, for example, uses POSITION and SIZE 
subqualifiers: 


$ SORT/KEY=(POSITION=29+sSIZE=30) SALES.DAT BILLING.LIS @@ 


POSITION and SIZE are the most important key subqualifiers. 
POSITION =n 


Here n stands for the position within the record of the first byte in the key 
field. (The first position in the record is considered 1.) This position was 
established when the file was created; you can often determine it by exam- 
ining a record from the file. 


Always specify the POSITION subqualifier. 


SIZE=n 


Here n stands for the length of the key field in characters, bytes, or digits. 
(The unit depends on whether the data type of the key field is character, 
binary, or decimal.) Omit the SIZE subqualifier only for floating point data 
types, which have fixed sizes. 


Any portion of a record can be a key. If you specify more than one key field, 
additional keys create suborders for records having the same primary key. 
You can sort records by as many as ten key fields with one command. 


Suppose you want to rearrange the sales records that were sorted in Section 
1.1 to show sales by department and by each salesperson in a department. 
Department code is the primary key and salesperson the secondary key. 
The command is: 


$ SORT /KEY=(POSITION=8 ySIZE=3) /KEY=(POSITION=11 ,SIZE=11) SALES.DAT 
DEPT.LIS ED 


Notice that you specify /KEY = followed by the necessary subqualifiers for 
each key by which you sort. Here is the reordered file you create with this 
command line: 


091580 19 Arndt 166392 Wilson Brent 1298 
091580 19 Erkkila 980342 Coolidge Carol 7200 
091580 25 Bradley 829582 Olsen Allen 3350 
091580 25 Bradley 753735 Rice Anne 10875 
091580 25 Fielding 980342 Coolidge Carol 24999 
091580 25 Sanchez G43881 McKee Michael 2499 
091580 28 Meredith 272731 Karsten Jane 4000 
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Records in the new file are in order by department code, the primary key. 
Notice that when more than one record has the same department code, the 
sort creates a suborder based on the secondary key, salesperson. If the 
command had specified a third key, another suborder could have been cre- 
ated for Bradley’s two sales records. 


/KEY needs additional subqualifiers if: 
© Key field data type is not character 
© You list keys in an order different from their priority in the sort 


e You want the sorted file in descending order (that is, highest to lowest 
number or Z to A) 


Section 2.1.2 describes the subqualifiers you use in these cases. 


1.1.3 Input File Parameter 


SORT accepts up to ten input files. Separate multiple input file specifica- 
tions by commas. For example, if you want to sort two days’ files of sales 
records by customer name, type: 


$ SORT/KEY=(POSITION=29 ,SIZE=30) SALES1,DAT;»SALES2.DAT BILLING.LIS fe 


The input file parameter accepts one qualifier, which you must use if your 
file is not on disk or ANSI magnetic tape. Section 2.1.1 describes this 
qualifier. 


1.1.4 Output File Parameter 


The command string may have only one output file specification. You need 
qualifiers for this parameter only if: 


e You want your output file to have a different format, organization, or size 
from your input file(s) 


e You are overwriting a file 


e You want contiguous blocks for your output file 


Section 2.1.3 explains the qualifiers you use in these circumstances. 


1.2 Merging Records 


The MERGE utility takes two to ten similarly sorted input files, merges 
them according to the key field(s) you specify, and generates a single output 
file. Note that input files to MERGE must be in sorted order. 


A central office might receive files of sorted sales records from eight stores, 
for example, and merge these files to create a single file. Or one store might 
merge sorted sales records each day with its main file. 
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1.2.1 The MERGE Command 
The MERGE command has three main parts, separated by spaces. 


@ 


ARTE TER, 
MERGE/|qualifier| input-file-specifications|qualifiers]| 


output-file-specification| qualifiers] 
a ete 


‘) 


1. Command name (MERGE) 


MERGE is the command name that invokes the VAX-11 MERGE util- 
ity. It takes three qualifiers, one of which describes the key(s) by which 
you want to merge your records. 


The MERGE command needs two parameters: 


e A list of file specifications of files to be merged 


e A name for the one merged output file 


2. Input file parameter 


This parameter specifies the sorted files you want to merge. You must 
specify at least two and not more than ten files, and key(s) must be the 
same in all files. Separate input file specifications with commas. 


3. Output file parameter 


This parameter specifies the merged file you want to create. Its quali- 
fiers can request characteristics for the merged output file. The com- 
mand string may have only one output file specification. 


The following example of a merge operation continues the sales records 
example of Section 1.1. The central store has received the file of sorted sales 
records (now renamed STORE1.FIL) and wants to merge them with a simi- 
larly sorted file from another store (STORE2.FIL). The two files, both in 
order by customer name, are shown below. 


STORE1.FIL 

091580 19 Erkkila 
091580 25 Fielding 
091580 28 Meredith 
091580 25 Sanchez 
091580 25 Bradley 
091580 25 Bradley 
091580 19 Arndt 
STORE2.FIL 

091580 20 QConnor 
091580 04 Docus 
091580 25 Fielding 
091580 35 Leith 
091580 04 Kramer 
091580 20 OConnor 
091580 19 ErkkKila 
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980342 
980342 
272731 
643881 
829582 
733735 
166392 


358419 
980342 
669011 
848105 
561903 
643881 
4354389 


Coolidge Carol 
Coolidge Carol 
Karsten Jane 
McKee Michael 
Olsen Allen 
Rice Anne 
Wilson Brent 


Beaulieu Ronald 
Coolidge Carol 
Fernandez Felicia 
Kingsfield Stanley 
Landsman Melissa 
McKee Michael 
YVanDerling Julie 


Nn 


29-58 


7200 
24999 
4000 
2499 
3350 
10875 
1298 


1598 
975500 
12000 
9550 
230000 
995 
5480 


The command to merge the two files is: 


$ MERGE /KEY=(POSITION=29;,SIZE=30) STORE1.FIL+STOREZ.FIL CENTR.FIL @et 


Use TYPE or PRINT to see the merged file. 


$ TYPE CENTR.FIL men 


091580 20 QConnor 358419 Beaulieu Ronald 1598 
091580 19 Erkkila 980342 Coolidge Carol 7200 
091580 25 Fielding 980342 Coolidge Carol 24999 
091580 04 Docus 980342 Coolidge Carol 575500 
091580 25 Fielding 669011 Fernandez Felicia 12000 
091580 28 Meredith 272731 Karsten Jane 4000 
091580 35 Leith 848105 Kingsfield Stanley 9550 
091580 O04 Kramer 561903 Landsman Melissa 230000 
091580 25 Sanchez 643881 McKee Michael 2499 
091580 20 OConnor 643881 McKee Michael 995 
091580 25 Bradley 829582 Olsen Allen 3350 
091580 25 Bradley 753735 Rice Anne 10875 
091580 19 Erkkila 454389 VanDerling Julie 5480 
091580 19 Arndt 166392 Wilson Brent 1298 


1.2.2 MERGE Qualifiers 


Three MERGE command qualifiers are available. You must always specify 
the /KEY qualifier. 


/KEY subqualifiers are the same as for SORT keys: you must specify 
POSITION and, except for key data types with fixed sizes, SIZE. POSITION 
is the position within the record of the first byte in the key field (where the 
first position in the record is considered 1). SIZE is the length of the key 
field in characters, bytes, or digits. 


/KEY subqualifiers follow the equals sign and are placed inside 
parentheses separated by commas. The simple merge just shown uses these 
two key subqualifiers: 


$ MERGE /KEY=(POSITION=29SIZE=30) STORE1.FIL+STORE2.FIL CENTR.FIL (ed 


Specify additional /KEY subqualifiers if: 


© Key field data type is not character 
e You list keys in an order different from their priority in the merge 


e Input file records have been sorted in descending order 


Section 2.2.2 explains the subqualifiers you use in these cases. 


1.2.3 Input. File Parameter 


The input file specification parameter accepts one qualifier. You need this 
qualifier if your file is not on disk or ANSI magnetic tape. 


If used, this qualifier must apply to all input files. 


See Section 2.2.1 for more details. 
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1.2.4 Output File Parameter 
Just as for SORT, you need qualifiers for this MERGE parameter only if: 


e Your output file has a different format, organization, or size from your 
input files 


e You are overwriting a file 


* You want contiguous blocks for your output file 


Section 2.2.3 explains the qualifiers you use in these circumstances. 


1.3 Running Batch SORT and MERGE 
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You can run your sort or merge task as a batch job. Batching frees your 
terminal for other work after you submit the job to the system for process- 
ing. Consider running frequent or lengthy sort and merge tasks as batch 
jobs. 


To prepare a batch job, you first create a command procedure. To run the 
sort of sales records shown in Section 1.1 as a batch job, create your com- 
mand procedure using a text editor or, as in this example, the CREATE 
command: 


$ CREATE SALES.COM fe 


Type in the following commands to sort the records in SALES.DAT by 
customer name and print out the reordered file: 


$ SORT /KEY=(POSITION=29,SIZE=30) SALES.DAT BILLING.LIS 
$ PRINT BILLING.LIS 


“a 


Once you have created the command procedure, you execute it by using the 
SUBMIT command: 


$ SUBMIT SALES.COM &et 


The system assigns the batch job an identification number and enters it in 
the batch job queue. Immediately after you type the SUBMIT command, 
the system displays a message giving you the job identification number. 
For example: 


Job 212 entered on queue SYS#$BATCH 


The system also creates a log file (in this example, SALES.LOG) to which it 
writes all output from the command procedure. When the batch job com- 
pletes, this file is printed out and then deleted. The printed output from 


this batch job, then, is the sorted file, BILLING.LIS, and the batch job log 


file, SALES.LOG. 
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You can submit multiple command procedures and qualify the SUBMIT 


command in various ways. For additional information, see the VAX/VMS 
Cc Command Language User’s Guide. 
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Chapter 2 
Qualifying SORT and MERGE Commands 


This chapter describes the command qualifiers, subqualifiers, and parame- 
ters you specify when you use the SORT or MERGE command. You can 
specify these instructions interactively at a terminal. You can also enter 
them into a batch command procedure (see Chapter 1) or, for SORT only, a 
specification file (see Section 2.4). If you want only a brief description of 
SORT and MERGE qualifiers, see Section 2.3. 


2.1 Qualifying the SORT Command 
The SORT command has three parts, separated by spaces: 


(ee ee ee 
SORT|qualifiers] input-file-specification[qualifier] 


output-file-specification| qualifiers] 
(steep eee eed 


© 


Sections 2.1.1. to 2.1.3. describe these three parts. The section describing 
the second part of the command line, input file specification, comes first ° 
because you need to consider the input file before you can determine what 
to specify for SORT command qualifiers and output file specification 
qualifiers. 


For quick reference, Figure 2-1 summarizes the SORT command qualifiers, . 
subqualifiers, and parameters. 


2.1.1 Input File Parameter 


Before entering the command line, first prepare the information SORT 
needs. Begin by determining the specification(s) of the file(s) you plan to 
sort. You provide this information in the second part of the command string 
as the input file parameter. Usually file name and type are an adequate file 
specification. (See the VAX/VMS Command Language User’s Guide if you 
need more information on file specification.) 


If you do not provide an input file specification, DCL prompts with: 


$_Files 


Default file type is DAT. 


2-1 


2-2 


You can sort up to ten files at once; separate their file specifications by 
commas. Multiple input files must have the same file organization, record 
format, and key description. VAX—11 SORT accepts all VAX—11 RMS files. 
That is, it accepts sequential, relative or indexed-sequential data files on 
one or more volumes, containing records of fixed, variable, or variable with 
fixed-length control format. Multiple input files with VFC record format 
must all have the same length control portion. SORT does not support 
FORTRAN segmented files. 


Suppose you plan to sort a file of records named READ.FIL, which gives 
results from reading tests taken by fourth-, fifth-, and sixth-grade students 
(see Figure 2-2). Specify READ.FIL as the input file parameter. 


$ SORT|QUALIFIERS] READ.FIL OUTPUT.FIL 


If you want to sort two files of similar records (for example, different 
schools in one system), list the files in this way: 


$ SORTI|QUALIFIERS] READ1.FIL,READ2.FIL OUTPUT.FIL 


Before carrying out a sort operation, VAX—11 SORT needs to know the size 
of the file(s) it is about to sort and the size of the longest record in the 
file(s). For files on disk or ANSI magnetic tape, VAX-11 Record Manage- 
ment Services (RMS) automatically provides information about record and 
file size to the SORT utility program. But if your input file is on an input 
device from which RMS cannot get file and record size, such as a terminal, 
you must provide this information by using the following qualifier and 
subqualifers immediately following input file specifications: 


/FORMAT = (RECORD-__SIZE = n,FILE__SIZE = n) 


RECORD_SIZE=n You specify record size by giving the longest record 
length (LRL) in bytes. The longest record length 
allowed is 32,767 bytes (16,383 for relative files). 
These totals include control bytes for VFC files. For 
multiple files, LRL is the longest record length of 
all records in all files. 


For additional information on determining the 
LRL, refer to the $FAB MRS parameter in the 
VAX-11 Record Management Services Reference 
Manual. 


In the case of an RMS error, you can use this 
subqualifier to override the record size normally re- 
trieved from RMS. 


FILE_SIZE =n You specify file size in blocks. Maximum file size 
accepted is 4,294,967,295 blocks. For multiple input 
files, n is the total size of all files. If file size is not 
provided by RMS or the user, SORT assumes 1000 
blocks. SORT uses file size information to deter- 
mine the size of its work files. 
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Figure 2-1: SORT Command Summary 


Command Format: $$ORT/QUALIFIERS INPUT.FIL/QUALIFIERS OUTPUT.FIL/QUALIFIERS 


$ SORT 



















SORT Qualifiers Subqualifiers and Values Notes 


/KEY= (| CHARACTER /KEY is not required with 
BINARY /SPECIFICATION 
F__FLOATING 
D__FLOATING 
G__FLOATING 
H__FLOATING 
ZONED 
DECIMAL 
PACKED__DECIMAL 


SIGNED Use with binary data 
UNSIGNED 


,TRAILING__SIGN Use with decimal data 
,LEADING__SIGN 


,OVERPUNCHED_ SIGN Use with decimal data 
sSEPARATE_SIGN 


,POSITION={1-32767} 


1-255 for CHARACTER data Required for all data types 
SIZE= (1,2,4,0r 8 for BINARY data except floating point 
1-31 for DECIMAL data 


[.NUMBER-|1-101] 


ASCENDING 
,DESCENDING }) 


/PROCESS RECORD 








[ /STABLE } 


/COLLATING__SEQUENCE- } ASCII 
EBCDIC 











[ /WORK_FILES-= 0,2-10} ] 

[/STATISTICS ] 

[ /SPECIFICATION [-file-specification) ] 

[/Asx11] Requires PDP-11 SORT 


command switches 


(continued on next page) 








Notation used: 
¢ Optional qualifiers are enclosed in brackets [ ]. Use one or none from a list enclosed in brackets. 
e For values enclosed in braces | | you must select one. 

¢ Defaults are shown in bold type. 
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Figure 2-1: SORT Command Summary (Cont.) 


INPUT.FIL/QUALIFIERS 9 


Input-file-specification(s) 


Input File Qualifiers Subqualifiers and Values Notes 


/FORMAT= (RECORD_SIZE={1-32767} Required for files not on disk or 
ANSI magnetic tape 
/FILE__SIZE=|1-4294967295}) Use with above files 
Default is 1000 blocks 


OUTPUT.FIL/QUALIFIERS 


Output-file-specification 


Output File Qualifiers Subqualifiers and Values Qo 


/FORMAT= FIXED=[1-32767] 
VARIABLE=[1-32767] 
CONTROLLED=[1-32767] 


[size-1-255 Use with CONTROLLED records 
Default is 2 bytes 


[sock_size-j18-65535) Use with tape files 
/SEQUENTIAL @) 
/RELATIVE 
/ANDEXED__SEQUENTIAL 
[/ALLOCATION= {1-4294967295) | Required with /CONTIGUOUS 
[/CoNnTIGUOUS ] Use with /ALLOCATION | 
[/LOAD_FILL ] Use with INDEXED files 
[/OVERLAY ] Required for INDEXED files 
[/BUCKET_SIZE-= Use with disk files eo) 
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If you specify only one /FORMAT subqualifier, you can omit the 
parentheses. 


If your two files of reading test records are not on disk or ANSI magnetic 
tape, your input file parameter looks like this example: 


READL.FIL»READZ2. FIL / FORMAT=(RECORD_SIZE=75 »sFILE_SIZE=6) 


Notice that you specify the /FORMAT qualifier once, following file specifi- 
cations for all input files. 


2.1.2 SORT Command Qualifiers 


As the first part of the command string, specify the command SORT 
followed by the qualifier(s) appropriate to your sorting task. SORT accepts 
eight qualifiers: 


/KEY 

/PROCESS 

/STABLE 
/COLLATING__SEQUENCE 
/WORK__FILES 
/STATISTICS 
/SPECIFICATION 

/RSX11 


The rest of this section explains these qualifiers. List the qualifiers in any 
order following the command SORT. 


/KEY 


After you have determined the needed input-file information, decide which 
data field(s) in your records you want to arrange in sequence. You can sort 
by one key field (student name, for example), by two (grade and name), or 
by any number of keys up to ten. If you select multiple keys, decide which is 
primary, which secondary, and so on. 


Suppose you want to arrange the reading scores from highest to lowest 
score for each class within each grade. Primary key is grade; secondary key 
is class (indicated by teacher name); tertiary key is score. 


For each key, you use key subqualifiers to provide the sort utility with 
information about: 


e The way key field data is stored in your records 
(DATA TYPE, POSITION, SIZE) 
e Your decisions for the sort 


- NUMBER, ASCENDING/ DESCENDING) 


Qualifying SORT and MERGE Commands 2-5 





Figure 2-2: A Sample Sort 


1. Observe the input file of reading test records (READ.FIL): 


Date 


03-10-80 
03-10-80 
03-10-80 
03-10-80 
03-10-80 
03-10-80 
03-10-80 
03-10-80 
03-10-80 
03-10-80 
03-10-80 
03-10-80 
03-10-80 
03-10-80 
03-10-80 
03-10-80 
03-10-80 
03-10-80 
03-10-80 
03-10-80 
03-10-80 
03-10-80 
03-10-80 
03-10-80 
03-10-80 


Gr = Teacher Student 
4 Anderson Brock Diane 
G ONeill Schillaci Rosemary 
3 Walczak Vaillancourt Roger 
G6 MacLeod Ecklund Kristine 
5 Reiner Sanchez Juan 
4 Marquez Bellermann Robert 
G ONeill Hartman Harold 
3 Reiner Wu Karen 
4 Anderson Braddon Michael 
G MacLeod Parker Ruthann 
4G Marauez Olanbak Raymond 
3 Walczak Cochrane Nancy 
4G Marauez Hanley Vivian 
G6 ONeill Cote Yvonne 
4 Anderson Nolan Keith 
3 Reiner Rodino Madeleine 
6 ONeill Grodinski Richard 
9 Reiner Kessler Peter 
3 Walczak Levine Carol 
4 Anderson Tillotson Judith 
G6 MacLeod Delano Paul 
4 Marauez James Joseph 
6 Macleod Fisher Carolyn 
3S Walczak Yuan Kim 
9 Reiner Lopez Edward 

11 14-28 
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Score Level 


470 +2 
20 - 3 
560 + 1 
740 +49 
590 +4 
470 +2 
590 - 6 
610 +6 
460 +1 
650 (a) 
650 +20 
S10 -4 
350 -10 
800 +15 
530 + 8 
540 - 1 
650 QO 
920 -3 
440 -11 
440 - 1. 
690 +4 
630 +18 
700 + 5 
S60 + 1 
650 +10 
wH oY 
54-46 59-61 


Test 


Bates-Mck 
Bates-Mck 
Bates-Mck 
Bates-Mck 
Bates-Mck 
Bates-Mck 
Bates-Mck 
Bates-Mck 
Bates-Mck 
Bates-Mck 
Bates-Mck 
Bates-Mck 
Bates-Mck 
Bates-Mck 
Bates-Mck 
Bates-Mck 
Bates-Mck 
Bates-Mck 
Bates-Mck 
Bates-MckK 
Bates-Mck 
Bates-McKk 
Bates-Mck 
Bates-Mck 
Bates-Mck 





2. Enter this command to arrange records from highest to lowest score for each class within each grade: 


$ SORT /KEY=(POSITION=11,SIZE=1) /KEY=(POSITION=14;SIZE=15) /KEY=(POSITION=54, 
SIZE=3 »DESCENDING) READ.FIL READ.LIS ‘Re 


3. The sorted output file (READ.LIS) is: 


Date Gr Teacher Student Score Level Test 
03-10-80 4 Anderson Nolan Keith 530 + 8 Bates-Mck 
03-19-80 4 Anderson Brock Diane 470 + 2 Bates-McK 
03-10-80 4 Anderson Braddon Michael 460 + 1 Bates-Mck 
03-10-80 4 Anderson Tillotson Judith 440 - 1 Bates-Mck 
03-10-80 4 Marauez Olanbak Raymond 650 +20 Bates-McKk 
03-10-80 4 Marauez James Joseph 630 +18 Bates-Mck 
03-10-80 4 Marauez Bellermann Robert 470 + 2 Bates-Mck 
03-10-80 4 Marauez Hanley Vivian 350 -10 Bates-Mck 
03-10-80 5S Reiner Lopez Edward 650 +10 Bates-Mck 
03-10-80 5 Reiner Wu Karen G10 + G6 Bates-Mck 
03-10-80 5 Reiner Sanchez Juan 590 + 4 Bates-McKk 
03-10-80 5 Reiner Rodino Madeleine S40 - 1 Bates-Mck 
03-10-80 5 Reiner Kessler Peter 920 - 3 Bates-Mck 
03-10-80 5 Walczak Yuan Kim SGO + 1 Bates-Mck 
03-10-80 5 Walczak Yaillancourt Roger SGO + 1 Bates-Mck 
03-10-80 5 Walczak Cochrane Nancy 510 - 4 Bates-McK 
03-10-80 5 Walczak Levine Carol 440 -11 Bates-Mck 
03-10-80 6G MacLeod Ecklund Kristine 740 + 9 Bates-Mck 
03-10-80 G6 MacLeod Fisher Carolyn 700 + 5 Bates-Mck 
03-10-80 G MacLeod Delano’ Paul 690 + 4 Bates-Mck 
03-10-80 6 MacLeod Parker Ruthann 650 oO Bates-Mck 
03-10-80 6 ONeill Cote Yvonne B00 +15 Bates-Mck 
03-10-80 6 ONeill Grodinski Richard 650 © Bates-Mck 
03-10-80 6 ONeill Schillaci Rosemary 620 - 3 Bates-Mck 
03-10-80 6 ONeill Hartman Harold 590 - G6 Bates-Mck 
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Figure 2-3: KEY Specifications 


Determine Data Type: 
Character (default) 
Binary ——» specify BINARY- 







Signed 
Unsigned ———» specify UNSIGNED 


Decimal: : 
Zoned ——-»specify ZONED 
Packed Decimal——— specify PACKED DECIMAL 


| f A 
Decimal ——» specify DECIMAL- Specity POSITION 


Specify SIZE 


Trailing Sign 
Leading Sign —» specify LEADING 





Overpunched Sign 
Separate Sign ———» specify SEPARATE 


Floating Point 
F Floating ——»specity F FLOATING 
D Floating» specify D FLOATING 
G_ Floating——» specify G FLOATING 
H Floating ——-» specify H FLOATING 


specify POSITION 


Keys listed in order? 
Yes —»use default numbering 
No——®specify NUMBER 


Ascending Sort? 
Yes 
No —»specify DESCENDING 





Enter key specifications 
into Command string 
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Figure 2-3 provides a chart for quick reference when you are specifying 
keys. 


DATA TYPE 


To provide SORT with the necessary information about your keys, you 
must first know the data type used for storing information in your key 
field. The program used to create the file(s) established the data type of 
each field in the record. 


The data types recognized by VAX-11 SORT are: 


CHARACTER (ASCII order or EBCDIC order) 

BINARY (SIGNED or UNSIGNED) 

F__FLOATING 

D__FLOATING 

G__FLOATING 

H__FLOATING 

ZONED 

DECIMAL (LEADING or TRAILING, SEPARATE or 
OVERPUNCHED) 

PACKED__DECIMAL 


CHARACTER is the default data type. If the data in your key field is 
not stored as character, you must specify the data type. 


In addition, if your key data type is unsigned binary, specify 
UNSIGNED. This subqualifier enables SORT to accept larger binary 
numbers; however, it treats all numbers as positive. SIGNED is the 
default. 


Finally, if your key data type is decimal, you must determine two more 
facts: 


e Whether the sign of the decimal data key is stored at the beginning or 
end of the key 


e Whether the sign is overpunched or is separated from the decimal 
TRAILING__SIGN or LEADING_SIGN: 


If the sign is stored at the end of the key, you do not need to type in 
any keyword. TRAILING__SIGN is the default. 


If the sign is stored at the beginning of the key, you must specify 
LEADING__SIGN. 
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OVERPUNCHED_SIGN or SEPARATE__SIGN: 
If the sign of your decimal key is overpunched, you do not need to 
specify anything. OVERPUNCHED__SIGN is the default. 


If the sign is separated from the decimal, you must specify 
SEPARATE_ SIGN. 


In the records in Figure 2-2, grade, teacher, and score are all stored as 
character data. For this sort, then, you do not need to use any data type 
subqualifiers. 


POSITION 


For every key, you must use POSITION = n. Here n is the position of the 


first byte of the key field within the record. The position of the first byte 
in a record is considered position 1. Positions of data fields were estab- 
lished when the file was created. 


In Figure 2-2, grade begins in position 11, teacher position 14, and 
score position 54. 


SIZE 


Unless your data type is one of the floating point data types (for which 
size is fixed), you must specify SIZE =n, where n is the length of the sort 
key. 


Depending on data type, you specify size in characters, bytes, or digits. 
If sort key data type is character, key size in characters must not be 
more than 255. If data type is binary, key size in bytes must be 1, 2, 4, 
or 8 (that is, byte, word, longword, or quadword). If the data type is any 
of the decimal types, key size in digits must not exceed 31. The total of 
all key field sizes must not be more than 255 bytes. 


Note that for decimal data, length is measured in digits, not in bytes. 
Thus, if the sign is stored in a separate byte (as it is for Leading Sep- 
arate and Trailing Separate decimal strings), that byte is not counted in 
figuring size. However, it is counted in figuring position. 


Remember this method of using digits to determine decimal size when 
key data type is packed decimal, which stores two decimal digits in one 
byte. 


The data field containing level in the reading-score records might con- 
tain the information stored as decimal with a leading, separate sign. In 
this case, key specifications are: 


/KEY=(POSITION=59 »SIZE=2 »+DECIMAL »LEADING »SEPARATE) 


When sorting data not stored as character, remember that certain non- 
character data should not be printed without being converted by a 
program. 
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In the example above, size for grade key is 1, for teacher 15, and for 
score 3. At this point, after you have considered data type, position, and 
size, key specifications are: 


SORT /KEY=(POS=11 *SIZE=1) /KEY=(POS=14 +SIZE=15) /KEY=(POS=54 ,SIZE=3) 


NUMBER 


If you are sorting on several keys, and you list them in an order differ- 
ent from the order of their priority in the sort, then you must specify the 
place of each key in the sort by using NUMBER=n. Acceptable values 
for n are 1-10, where 1 is the primary sort key, 2 is the secondary sort 
key, and so on. If you do not specify NUMBER, SORT assigns 
NUMBER = 1 for the first key you list, and the NUMBER value of the 
previous key plus 1 for each following key. 


Of course, if you define your keys in order of decreasing priority, you 
can omit this subqualifier; SORT assigns the appropriate numbers. 


ASCENDING/DESCENDING 


SORT normally arranges records in ascending order (that is, A to Z or 
lowest to highest number). ASCENDING is the default. If you want to 
sort any key in descending order, you must indicate this by specifying 
DESCENDING as a key subqualifier. 


In the example, you want to arrange reading scores so the highest score 
in each class is first. This is a descending sort, and you must use the 
DESCENDING subqualifier with this key. 


You must specify these key subqualifiers and values for each key field 
by which you sort your file. List key subqualifiers inside parentheses 
following /KEY= and separate them with commas. You can list them 
in any order. 


/PROCESS 


SORT offers four processes by which you can sort your records: 


/PROCESS = RECORD 
/PROCESS = TAG 
/PROCESS = ADDRESS 
/PROCESS = INDEX 


Depending on which process you select, your output file contains the 
records themselves (record or tag sort) or an index to the records (address 
or index sort). You must submit this index to a program for further 
processing. 
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The four processes differ also in input and output device requirement, num- 
ber of input files accepted, and processing method. You must understand . 
these differences to select the process best suited to your sorting task. Table & ) 


2-1 shows these differences. 
Output 
Device 


any VAX/VMS 
output device 


Table 2-1: SORT Processes 


Input Processing Output File 
Process Device . Method Content 


Record 















single or 
multiple 
files 


keeps record 
intact 
throughout sort 


complete 
records 


any 
VAX/VMS 
input device 










































any VAX/VMS 
output device 


complete 
records 


disk only one file sorts only key(s), 
then reaccesses 
input file records 
to create output 


file 


Tag 
























Address one file 





any device that 
accepts binary 
data 


disk only sorts only key(s) | binary RFAs 
only 
(Record File 


Address) 



















one file 












sorts only key(s) | keys and 


binary RFAs 


any device that 
accepts binary 
data 


disk only 






Selecting a Sort Process J 
1. Consider first how you will use the output file. 


¢ Record and tag sort generate files containing, the entire records. 
These reordered files are ready to be printed out and distributed, or 
stored. 


¢ Address sort creates a list of pointers to the records in the input file. 
This list takes the form of binary Record File Addresses (RFAs). A. 2) 
program can use the list of pointers to access records in the rear- 
ranged order for further processing or later output. 


¢ Index sort creates an output file containing both RFAs and key fields. 
If your program needs key field content for decision during future 
processing, select index sort rather than address sort. Because the 
output file from index sort contains key field data, the processor does 
not have to get it from auxiliary storage. (Do not confuse this index 
file generated by SORT with RMS indexed file organization.) 


You may need to arrange the same data in several ways for different 

purposes. Sales records, for example, can provide the basis for billing 

customers, updating inventory, and keeping track of sales by depart- 

ment and salesperson. Instead of storing several versions of the same 

file, you can store several output files from address or index sort in 
much less space. Then use these files to access the records in the main oS 
file in the order you want. 
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2. Also consider the temporary storage space you have available for the 
sort. 


e Tag sort uses less temporary storage space than record sort, which, 
because it keeps the record intact during the sort, can take up much 
work space for large files. 


e Address and index sort use little space. 


3. Input and output device and number of input files can also affect your 
selection of sort process. 


e Record sort is the only process that can accept input from cards and 
magnetic tape as well as disk. 


¢ Output from address and index sort must go to a device that accepts 
binary data. 


e Only record sort accepts multiple input files. 
4. Finally, consider differences in speed. 


e If you plan to retrieve the sorted records in order at some point in 
your operation, record sort will usually be the fastest process. 


e Because tag sort moves only keys instead of complete records, it can 
be faster than record sort when record size is very large and key size 
is small. Tag sort can also be faster for exceedingly large files and 
devices with a fast seek time. In most cases, however, the time tag 
sort takes to reaccess the input file makes it slower than record sort. 


e Address and index sort are the fastest processes (but of course do not 
output the records). 


Record sort is the default sort process. 


For the reading score sort (Figure 2-2), you want to print out the reordered 
file, which means you should select either record or tag sort. You have 
adequate temporary storage space, and record size is not large enough to 
suggest that tag sort might be faster than record sort. The best choice then 
is record sort, the default process. 


If instead of printing out the sorted records, you want to submit them to a 
program for determining median score in each class and grade, select an 
index sort and include in your command the qualifier: /PROCESS= 
INDEX. Note, however, that if you have multiple input files, you must 
select record sort. 


/STABLE 


If you request stable sort, SORT keeps records with equal keys in their 
original order. Otherwise, their order in the output file is unpredictable. 
Because this capability takes additional memory, use it only when your 
sorting task requires keeping records with the same keys in the same order. 


If you use /STABLE, maximum key size is 251 instead of 255. 
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/COLLATING__SEQUENCE 


SORT arranges characters in ASCII sequence. If you want SORT to arrange 
characters in EBCDIC sequence (for example, a program may require an 
input file in EBCDIC sequence), specify /COLLATING_ 
SEQUENCE =EBCDIC. Note that the characters remain ASCII represen- 
tation; only the order changes. 


COLLATING__SEQUENCE = ASCII is the default. 


/WORK__FILES 


You can instruct SORT to use no work files or any number from 2 through 
10. SORT does not create work files until it needs them. Then, unless 
instructed differently, it creates two temporary work files for your sort, 
determining their size from the size of your input file(s). 


Usually there is no advantage to using more than two work files. However, 
if you have plentiful work space on disk and want a faster sort, you can 
change the location of the work files. See Chapter 4 for more information. 


You assign a work file to a device other than your current default device by 
typing: 


$ ASSIGN (device): SORTWORKn 


SORTWORKn is a logical name for the work file, where n indicates the 
number of the work file. Acceptable values are 0 through 9. 


STATISTICS 


If you want a statistical summary at the end of your sort operation, use this 
qualifier. The statistical summary includes, among other things, the num- 
ber of records read, sorted, and output, and the maximum working set used. 
Section 4.2 explains how the information from this summary can help you 
improve your SORT efficiency. 


/SPECIFICATION 


A specification file is a file containing the sort instructions usually 
conveyed by the SORT qualifiers. If you use this method to perform 
your sorting task, in the SORT command you need only the qualifier 
/SPECIFICATION| = file-specification] in the SORT command. See Section 
2.4 for an explanation of specification file. 


/RSX11 


You can invoke SORT-11 instead of VAX-11 SORT by specifying this qual- 
ifier. If you select this option, use DCL (DIGITAL Command Language) 
syntax with PDP-11 SORT qualifiers. Refer to the PDP-11 SORT Reference 
Manual for more information. 
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2.1.3 Output File Parameter 


The third part of the SORT command string is the file specification of your 
output file. Specify only one output file. The output file in Figure 2-2 is 
READ.LIS. 


If you do not provide an output file specification, DCL prompts with: 


$_ Output: 


If you omit file type from your file specification, SORT defaults to the file 
type of the first input file. 


The output file parameter accepts seven qualifiers (one of which has three 
subqualifiers). Many sort operations do not use any of these qualifiers. The 
following list gives conditions under which you need a qualifier and the 
appropriate qualifier or subqualifier. The rest of this section explains how 
to use each qualifier. List any qualifiers immediately after output file 
specification. 


You need a qualifier if: 


e You want output file record format to differ from input file record format: 


/FORMAT = (FIXED =n 
(VARIABLE =n 
(CONTROLLED = n 


e You want the fixed portion of a controlled record to differ from input file 
fixed portion size: 


SIZE =n 


e You want the block size of a magnetic tape output file to differ from input 
file block size: 


BLOCK_SIZE = n) 


© You want the file organization of your output file to differ from that of the 
input file: 


/SEQUENTIAL 
/RELATIVE 
/INDEXED__SEQUENTIAL 


e You want to allocate a certain number of blocks on disk for your output 
file: 


/ALLOCATION =n 


e You want contiguous allocation of blocks for the output file: 


/CONTIGUOUS 
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¢ You are sorting an indexed file and want SORT to load buckets according 
to the fill size established when the file was created: 


/LOAD__FILL . ) 


¢ You want to overwrite an existing empty file which has the same name as 
the output file: 


/OVERLAY 
e You want to specify RMS bucket size for the output file: 
/BUCKET_SIZE=n 


The following paragraphs explain each of these qualifiers further. 


/FORMAT = (FIXED=n 
(VARIABLE =n 
(CONTROLLED =n 


Use this qualifier if you want your output file record format to differ from S) 
input file record format. You can specify fixed-length records (FIXED), 
variable-length records (VARIABLE), or variable with fixed-length control 

records (CONTROLLED). If you omit this qualifier, output record format is 

the same as input file record format if you are performing record or tag sort, 

and FIXED for address or index sort. 


You can also specify with each format subqualifier the longest record 

length (LRL) in bytes of the output records (n). LRL is optional. The longest a 
record length allowed is 32,767 bytes (16,383 bytes for relative files). These J 
totals include control bytes. For additional information on determining 

LRL, refer to the $FAB MRS parameter in the VAX-11 Record 
Management Services Reference Manual. 


SIZE=n 


Include this qualifier for CONTROLLED records only. It specifies the 

byte size of the fixed portion. Default size is that of the input file if it 

contains CONTROLLED records, or 2 bytes if input file record format is S) 
not CONTROLLED. Maximum size is 255 bytes. 


BLOCK__SIZE = n) 


Use this qualifier with magnetic tape files only. Specify the block 
length of the output file in bytes. Default value is the block size estab- 
lished at tape mounting time, or if no size was specified, the block size of 
the input file tape. Block size must be 18 to 65,535 bytes. 


NOTE 


To assure correct data interchange with other DIGITAL 
systems, specify a block size of not more than 512 bytes. 
To assure compatibility with most non-DIGITAL sys- 
tems, the block size should not exceed 2048 bytes. 2) 
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/SEQUENTIAL 
/RELATIVE 
/INDEXED__SEQUENTIAL 


You can use one of these qualifiers to specify output file organization. If you 
omit this qualifier, output file organization is the same as input file organi- 
zation for record or tag sort, and /SEQUENTIAL for address or index sort. 


If you specify /INDEXED__SEQUENTIAL (or if the output file is 
INDEXED__SEQUENTIAL by default), the output file must exist, its 
organization must be indexed sequential, and it must be empty; therefore, 
you must also specify /OVERLAY. 


/ALLOCATION =n 


You can allocate a certain number of 512-byte blocks of disk space for your 
output file. Acceptable values are from 1 to 4 294,967,295. 


If you plan to extend a file, or if you want a contiguous allocation of blocks, 
use this qualifier. 


/CONTIGUOUS 


You can require contiguous allocation of blocks for your output file by 
specifying /CONTIGUOUS. This qualifier must be used with 
/ ALLOCATION. It is invalid if you have not specified / ALLOCATION, or if 
/ ALLOCATION value is not large enough for total output and the file must 
be extended. 


/LOAD_FILL 


Use this qualifier only with INDEXED files. It loads the buckets according 
to the fill size established when the file was created, by using the 
$XABKEY DFL and $XABKEY IFL parameters. This procedure minimizes 
bucket splitting if many records are added later. See the VAX—11 Record 
Management Services Reference Manual for more information. 


/OVERLAY 


Use /OVERLAY to write the sorted file into an existing file. The existing 
file must be empty. 


/BUCKET_SIZE =n 


You can specify RMS bucket size (that is, the number of 512-byte blocks 
per bucket) for the output file by using this qualifier. If output file has the 
same file organization as input file, default value is the same as the input 
file bucket size. If output file organization is different, default value is 1. 
The maximum number of blocks per bucket is 32. 
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2.2 Qualifying the MERGE Command 


The MERGE command enables you to combine up to ten similarly sorted. : ) 
files. Like the SORT command, the MERGE command has three parts, 
separated by spaces: 


a Raa a Ca aa eae 
MERGElqualifiers] input-file-specifications| qualifiers] 


output-file-specification| qualifiers] 
nD | 


@ 


Sections 2.2.1 to 2.2.3 describe these three parts. The section describing the 

second part of the command line, input file specifications, comes first 

because you need to consider the input file before you can determine what 

to specify for MERGE command qualifiers and output file specification ; 
qualifiers. Figure 2-4 provides a summary of MERGE command qualifiers, 2) 
subqualifiers, and parameters for quick reference. 


2.2.1 Input File Parameter 


Before entering the command line, prepare the information MERGE needs. 

Begin by determining the file specifications of the files you plan to merge. 

You provide this information in the second part of the command string as 

the input file parameter. You must give at least two file specifications and ji 
not more than ten. Separate file specifications by commas. 2 


If you do not provide input file specifications, DCL prompts with: 


$_File: 


Usually you need only file name and type for each file. If any input file 
specification does not contain file type, MERGE defaults to DAT. 


Files must have the same record and key characteristics. For example, you 2 
cannot merge the file READ.LIS (Figure 2-2) with a file of reading test 

records that have the key fields in different positions. Files of records, 

though, can contain varying data as long as key fields remain the same. 


Input files must also have the same file organization. If they do not, you can 
convert them to the same organization by using the CONVERT/MERGE 
utility. See the VAX-11 Record Management Services Reference Manual on 
how to convert file organization. 


The input file parameter accepts one qualifier. This qualifier accepts two 


subqualifiers. To this qualifier, place it after the list of input file specifica- 
tions. This qualifier must apply to all input files. 
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Figure 2-4: MERGE Command Summary 


Command Format: $MERGE/QUALIFIERS INPUT.FLS/QUALIFIERS OUTPUT.FIL/QUALIFIERS 


$ MERGE 


MERGE Qualifiers Subqualifiers and Values 


/KEY = ( {CHARACTER 
BINARY 
F__FLOATING 
D__FLOATING 
G_FLOATING 
H__FLOATING 
ZONED 
DECIMAL 
PACKED__DECIMAL 


SIGNED Use with binary data 
UNSIGNED 


sep beech, Use with decimal data 
,LEADING.__SIGN 


,OVERPUNCHED_ SIGN Use with decimal data 
SSEPARATE__SIGN 


,POSITION={1-32767} 


1-255 for CHARACTER data 
SIZE= }1,2,4,0r 8 for BINARY data Required for all data types 
1-31 for DECIMAL data except floating point 


[.NUMBER=}1-10} ] 


ASCENDING 
,DESCENDING |) 


[/CHECK__SEQUENCE | 


/COLLATING__SEQUENCE-JASCH 
EBCDIC 


(continued on next page) 


Notation used: 

* Optional qualifiers are enclosed in brackets [ ]. Use one or none from a list enclosed in brackets. 
¢ For values enclosed in braces | | you must select one. 

* Defaults are shown in bold type. 
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/FORMAT =(RECORD__SIZE = n,FILE_SIZE = n) 


The MERGE utility needs to know: (1) the size of the files it is about to 
merge and (2) the size of the longest record in those files. For files on disk 
or ANSI magnetic tape, RMS automatically provides information about 
record and file size to the MERGE utility program. But if your input file is 
on an input device from which RMS cannot get file and record size, such as 
a terminal, you must provide this information by using the following quali- 
fier and subqualifiers immediately following input file specifications: 


RECORD_SIZE=n You specify record size by giving the longest record 
length (LRL) in bytes. The longest record length 
allowed is 32,767 bytes (16,383 bytes for relative 
files). These totals include control bytes. For multi- 
ple files LRL is the longest record in all input files. 


For additional information on determining the 
LRL, refer to the $FAB MRS parameter in the 
VAX-11 Record Management Services Reference 
Manual. 


In the case of an RMS error, you can use this 
subqualifier to override the record size normally 
retrieved from RMS. 


FILE_SIZE =n You specify file size in blocks. Here n is the total 
size of all input files. Maximum file size accepted is 
4,294,967,295 blocks. If file size is not provided by 
RMS or the user, MERGE assumes 1000 blocks. 


If you specify only one /FORMAT subqualifier, you can omit the 
parentheses. 


2.2.2 MERGE Command Qualifiers 
The MERGE command accepts three qualifiers: 


/KEY 
/CHECK_SEQUENCE 
/COLLATING__SEQUENCE 


You must always specify /KEY. 


Keys must be the same in all files to be merged. MERGE key subqualifiers 
are the same as SORT key subqualifiers. Remember, you merge sorted files 
on keys already used for sorting. You should know how the files you plan to 
merge have been sorted. You determine data type, position, and size in the 
same way for both SORT and MERGE. The subqualifiers NUMBER and 
DESCENDING refer to the order in which keys have been sorted in your 
input files. See Section 2.1.2 for information about key subqualifiers. 
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Keys in MERGE input files must be arranged in the same order. For exam- 
ple, READ.LIS, the file sorted in Figure 2-2, arranged reading scores from 
highest to lowest score within class. You cannot merge READ.LIS with a 
file of similar records arranged from lowest to highest reading score if you 
plan to merge on that key. However, you can merge the two files by grade 


and teacher as long as these fields are arranged in similar order in both 
files. 


/CHECK__SEQUENCE 


If you use this qualifier, MERGE checks your input files to make sure they 
are in order. If a record is out of order, MERGE gives you the following 
message at the end of the merge operation: 


%SOR-F-BAD_ORDER Input file En] is out of order 
In place of n, MERGE specifies the number of the input file (1-10). 


You must use /COLLATING_SEQUENCE = EBCDIC if sorted files are in 
EBCDIC sequence. 


2.2.3 Output File Parameter 


MERGE combines all input files into one merged output file. Give the 
output file specification as the third part of the MERGE command. Specify 
only one output file. 


If you do not provide an output file specification, DCL prompts with: 
$_ Outputs: 


If you omit file type from your file specification, MERGE defaults to the file 
type of your first input file. 


The MERGE output file parameter accepts the same seven qualifiers as 
does the SORT output file parameter. Many merge operations do not need 
any of these qualifiers. You need one or more only if: 


¢ You do not want to accept MERGE default values for organization, for- 
mat, and size 


¢ You are overwriting an existing file 
¢ You want contiguous blocks for your output file 


Use MERGE output file qualifiers in the same way as SORT output file 
qualifiers. See Section 2.1.3 for a description of these qualifiers. 
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2.3 Qualifier Summary 


This section provides a brief description of the qualifiers you can use with 
the SORT or MERGE command. Default values are in bold type. 


2.3.1 SORT/MERGE Command Qualifiers 


/KEY =(subqualifier,subqualifier...) 


The /KEY qualifier must be specified unless defined in a specification file. 
It defines a SORT or MERGE key, and may appear up to ten times ina 
command line. 


Enclose the /KEY subqualifiers group in parentheses. 


(POSITION =n 


The POSITION subqualifier is mandatory. Here n specifies the position 
of the first byte of the key field within the record, where the first posi- 
tion in the record is considered 1. 


SIZE=n 


The SIZE subqualifier is mandatory except for the floating point data 
types. Here n specifies the length of the sort or merge key in characters, 
bytes, or digits, depending on the key field data type. If key data type is 
CHARACTER, key size in characters must not be more than 255. If 
data type is BINARY, key size in bytes must be 1, 2, 4, or 8 (byte, word, 
longword, or quadword). If data type is any of the DECIMAL types, key 
size in digits must not exceed 31. Note that for decimal data, SIZE is 
measured in digits, not bytes. The total of all key field sizes must not be 
more than 255 bytes. 


CHARACTER 
BINARY 
F__FLOATING 
D__FLOATING 
G__FLOATING 
H__FLOATING 
ZONED 

DECIMAL 
PACKED__DECIMAL 


This subqualifier indicates the data type used for storing information in 
the key field. CHARACTER is the default data type. 


SIGNED 
UNSIGNED 


Use this subqualifier with binary data. It indicates whether a binary 
key is to be compared as a signed or an unsigned integer. UNSIGNED 
causes SORT to treat all numbers as positive. SIGNED is the default. 
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TRAILING_SIGN 
LEADING__SIGN 


Use this subqualifier with decimal data. It indicates whether the sign is 
stored at the beginning or end of the key. TRAILING__SIGN is the 
default. 


OVERPUNCHED_SIGN 
SEPARATE_SIGN 


Use this subqualifier with decimal data. It indicates whether the sign 
is overpunched or is separated from the decimal. The default is 
OVERPUNCHED_SIGN. 


For decimal data with a separate sign, ignore the sign byte in figuring 
size. 


NUMBER=n 


Use this subqualifier if you do not list your keys in order of descending 
priority. Here n specifies the priority of the key in the sort or merge 
operation. Acceptable values for n are 1-10, where 1 is the primary sort 
key, 2 is the secondary sort key, and so on. 


If you do not specify NUMBER, SORT assumes NUMBER = 1 for the 
first key you list, and the NUMBER value of the previous key plus 1 for 
each following key. 


ASCENDING 
DESCENDING ) 


This subqualifier indicates whether the key is to be sorted or merged in 
ascending or descending order. (Ascending order is A to Z or lowest to 
highest number.) ASCENDING is the default. 


/PROCESS = RECORD 
TAG 
ADDRESS 
INDEX 


Use /PROCESS with SORT only. It indicates the type of sort to be per- 
formed. /PROCESS = RECORD is the default. 


/STABLE 


Use /STABLE with SORT only. It causes SORT to keep records with equal 
keys in the same order as in the input file. For multiple input files, records 
with equal keys in the first file will be placed before those from the second 
file, and so on. 


If you use /STABLE, maximum key size is 251 instead of 255. 
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/CHECK_SEQUENCE 
Use /CHECK__SEQUENCE with MERGE only. It causes MERGE to check 
all input files for correct sequence. 
/COLLATING_SEQUENCE= ASCII 
EBCDIC 


This qualifier specifies the collating sequence to be used for character keys. 
COLLATING__SEQUENCE=EBCDIC causes ASCII characters to be 
sorted according to the EBCDIC sequence; characters remain ASCII repre- 
sentation. For MERGE, this qualifier specifies the sequence in which input 
records are arranged. COLLATING_SEQUENCE = ASCII is the default. 
/WORK_FILES =n 


Use /WORK__FILES with SORT only. Here n specifies the number of tem- 
porary work files to be used during the sort. Acceptable values are 0 and 2 
through 10. The default number of work files is 2. 

/STATISTICS 

Use /STATISTICS with SORT only. It causes SORT to display a statistical 
summary at the end of your sort operation. 

/SPECIFICATION| = file-specification ] 


Use /SPECIFICATION with SORT only. It causes SORT to refer to a speci- 
fication file for SORT instructions. You can specify the name of the file 
which contains these instructions; if no file name is given, SYS$INPUT is 
assumed. 

/RSX11 

Use this qualifier to invoke SORT-11. /RSX11 requires PDP-11 SORT 
qualifiers with DCL syntax. 


2.3.2 Input File Qualifiers 


List the input file qualifier once following all (one to ten) input file specifi- 
cations. The qualifier must apply to all input files. 
/FORMAT = 

(RECORD_SIZE =n 


Use this subqualifier if record size is not to be obtained from RMS. Here 
n specifies the longest record length (LRL) in bytes of all input files. The 
longest record length allowed is 32,767 bytes (16,383 for relative files). 
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FILE_SIZE = n) 


Use this subqualifier if file size is not to be obtained from RMS. Here n 
specifies the input file size in blocks. Maximum file size accepted is 
4,294,967,295 blocks. For multiple input files, n is the total size of all 
files. 


If file size is not provided by RMS or the user, SORT assumes 1000 
blocks. SORT uses file size information to determine the size of its work 
files. 


If you specify only one /FORMAT subqualifier, you can omit the 
parentheses. 


2.3.3 Output File Qualifiers 


List only one output file specification. 


/FORMAT = 


(FIXED=n 
(VARIABLE =n 
(CONTROLLED =n 


Use this qualifier if you want your output file record format to differ 
from input file record format. You can specify fixed-length records 
(FIXED), variable-length records (VARIABLE), or variable with fixed- 
length control records (CONTROLLED). Default output record format is 
the same as input file record format if you are performing record or tag 
sort, and FIXED for address or index sort. 


You can also specify with each format subqualifier the longest record 
length (LRL) of the output records (n). LRL is optional. The longest 
record length allowed is 32,767 bytes (16,383 bytes for relative files). 


SIZE =n 


Use this qualifier for CONTROLLED records only. Here n specifies the 
size in bytes of the fixed portion of CONTROLLED records. Maximum 
size is 255 bytes. Default size is that of the input file if it contains 
CONTROLLED records, or 2 bytes if input file record format is not 
CONTROLLED. 


BLOCK_SIZE = n) 


Use this qualifier with magnetic tape files only. Specify the block 
length of the output file in bytes. Default value is the block size estab- 
lished at tape mounting time or, if size was not specified, the block size 
of the input file tape. Block size must be 18 to 65,535 bytes. 


NOTE 


To assure correct data interchange with other DIGITAL 
systems, specify a block size of not more than 512 bytes. 
To assure compatibility with most non—DIGITAL sys- 
tems, the block size should not exceed 2048 bytes. 
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/SEQUENTIAL 
/RELATIVE 
/INDEXED_SEQUENTIAL 


These qualifiers specify output file organization. Default output file organi- 
zation is the same as input file organization for record or tag sort, and 
/SEQUENTIAL for address or index sort. 


If you specify /INDEXED_SEQUENTIAL (or if the output file is 
INDEXED__SEQUENTIAL by default), the output file must exist, its 
organization must be indexed sequential, and it must be empty; therefore, 
you must also specify /OVERLAY. 


/ALLOCATION =n 

This qualifier causes allocation of a certain number (n) of 512—byte blocks 
of disk space for your output file. Acceptable values are from 1 to 
4,294,967 ,295. 

/CONTIGUOUS 

This qualifier indicates contiguous allocation of blocks for your output file. 
It must be used with /ALLOCATION. 

/LOAD_FILL 

Use this qualifier only with indexed files. It loads the buckets according to 
the fill size established when the file was created. 

/OVERLAY 

Use /OVERLAY to write the sorted or merged file into an existing empty 
file. 

/BUCKET_SIZE=n 


This qualifier specifies the number of 512-byte blocks per bucket for the 
output file. Default value is the same as the input file bucket size if input 
and output files have the same file organization; if they do not, default 
value is 1. The maximum number of blocks per bucket is 32. 


2.4 Specification File 


A specification file enables you to instruct the sort utility without listing 
qualifiers in a command line. Instead, you enter the qualifiers in a speci- 
fication file and refer SORT to that file for instructions. Sorting with a 
specification file can prevent errors and save time in frequently performed 
sorting operations. 


VAX-11 SORT accepts specification files created for SORT-11; however, it 
does not accept record type specifications or ALTSEQ records. That is, you 
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cannot omit records from your sort or specify an alternate collating 
sequence. 


A specification file must contain two types of records: 


e A Header Record, which tells the SORT program which sorting process 
you want and establishes either ascending or descending as “normal” 
sorting order 


* One Field Specification Record for each key by which you want to sort. 


This record specifies data type, position, size and sorting order for that 
key 


You can format these records in one of two ways: 


¢ Fixed position field format: You enter data in fixed position fields based 


on card columns. This format permits conversion from SORT-11 specifi- 
cation files. 


¢ Free field format: You enter data in the same order as fixed format but in 
variable-length fields separated by commas. 


2.4.1 Header Record 


The first record in a specification file must be the Header. It tells SORT the 
sorting process and order you want. You also enter information about key 
size and output record size here. 


Enter instructions in the positions or order shown in Table 2-2. For free 
field format, enter a comma after each field, whether or not you enter data 
there. Notice that VAX-11 SORT does not use all available fields. 


Explanation 


Identifies position of this record in your specifica- 
tion file 
Optional (for documentation purposes) 


Table 2-2: Header Record 






Identifies this record as Header Record 






Specifies the sorting process you want 
SORTR (record sort) is the default 

SORTT (tag sort), SORTA (address sort), and 
SORTI (index sort) are options 







Specifies total of all key field sizes 
Optional for disk files 






Establishes ascending (A) or descending (D) as 
“normal” sort order for keys 
Ascending is default 











1-9999 Specifies largest output record length 


Optional for disk files 






Comments | May be used for comments 


Precede free field entries by! 





° 





Notice that fields 1 and 7 (columns 1-2 and 19-28) are not used; SORT 
ignores any data in these columns. However, in free field format you must 
place commas after these fields. 


In fixed field format, all numeric entries must be right-justified, either 
leading zeroes or blanks are acceptable. 


2.4.2 Field Specification Record 


Create one Field Specification Record for each key you plan to sort by. 
Enter them in your specification file in order of priority. Again, some fields 
are not used but need commas in free field format. Table 2-3 shows the 
order or position of fields. 


Table 2-3: Field Specification Record 


dd 
2 3-5 2-11 


Identifies position of this record in your specifica- 
tion file 
Optional (for documentation purposes) 













Identifies record as Field Specification 


Specifies sorting order for this key as “Normal” or 
“Opposite” the order established in field 6 of the 
Header 
















Specifies code for data type 
C = ASCII Character (the default) 
B = Binary 
F = Single or double floating point 
D = Decimal with sign trailing and overpunched 
= Decimal with sign leading and separate 
= Decimal with sign trailing and separate 
= Decimal with sign leading and overpunched 






NUASC™OBDWOA 


1-—32737 Position of first byte of key field 


Omit for one-byte keys 
Position of last byte of key field 





1-32737 





May be used for comments 
Precede free field entries by ! 


Comments 


Notice that fields 1 and 8 (columns 1—2 and 17-19) are not used; any data 
in these columns is ignored. However, in free field format you must place 
commas after these fields. 


NOTE 


VAX-11 SORT does not support G or H floating-point, 
EBCDIC, or unsigned data in a specification file sort. 


Figure 2-5 shows specification files in both formats created for the reading- 
score sort done earlier in this chapter (Figure 2-2). 
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DEC 7-4302)-1133a-R 1372 





Figure 2-5: Sample Specification Files 






Fixed Field Position Specification File 


Column 
5 10 15 20 25 30 
















1H SORTR 19A BOHeader Record 

2FNC00000011 Field Specification for grade 
3FNC00140028 Field Specification for teacher 
4FOC00540056 Field Specification for score 
















- Free Field Specification File 







*l+H+SORTR+19,A0, 1BO+!Header Record 
12+F oNoCoohtys! Field Specification for Srade 
*39F N10 114528,;!Field SPpecification for teacher 
945F 5050 +54556,9!Field Specification for score 











For purposes of illustration, values available by default are filled in. 





Digital Equipment Corporation provides a form, “Sort Specifications,” 
which helps you select and arrange the data you need to create a specifica- 
tion file. Figure 2-6 shows this form. 


Figure 2-6: SORT Specifications 
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ee 0 SUTRRCERUROREDOESER 
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-—-— Comments 
Field Location 7 


Record Name 















ys la Buunuanneare 
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FIELD marl 








Frekt Locetun 
NOT USED 
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2.4.3 Specification File Commands 


You can enter specification file instructions by writing the Header Record 
and Field Specification Record(s) into a specification file. 


If you have created a specification file in this way, type the SORT command 
as follows, placing the file specifications for your specification file 
(SPEC.FIL), input file INPUT.FIL), and output file (OUTPUT.FIL) in the 
indicated positions: 


$ SORT/SPECIFICATION=SPEC.FIL INPUT.FIL OUTPUT.FIL 


SORT then executes. 


You can also enter specification file instructions at the terminal when you 
invoke the SORT utility. 


Instead of creating a specification file, you can type: 


$ SORT/SPECIFICATION INPUT.FIL OUTPUT.FIL @ 


DCL prompts with: 


PLEASE ENTER SPECIFICATION FILE RECORDS 


You can then enter the data for the Header Record on the first line, press 
return, and enter Field Specification data for the primary key on the next 
line. Continue entering key data on each following line until you have 
entered specifications for all keys. Then type CTRL/Z to indicate comple- 
tion of your entries, and SORT executes. You can enter data in either free 
or fixed format. See Figure 2—7 for an example of prompted specification 
file instructions. 


Figure 2-7: Prompted Specification File 


$ sort/specification read.fil read-lis (é 


PLEASE ENTER SPECIFICATION FILE RECORDS. 


sL»HsSORTR 119 2A+ 280» 
r2eF oNoCooll oe 

13eF oNoC 0142285» 
149F »0»C 54569 


am 
a 





If you type only: 


$ SORT/SPECIFICATION Ge 


SORT first prompts for input and output files, then requests specification 
file records. 
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Chapter 3 
Calling SORT and MERGE from User Programs 


Often your sort or merge task is part of a larger operation you are perform- 
ing on your files. Perhaps you want to process the records in some way 
before you sort them, or after they are sorted and before you print or store 
them. Or you may want to select certain records from your files, merge 
them, then print or display the merged file. In such cases, you can call sort/ 
merge subroutines from a program you write to perform several tasks. 


Eight subroutines, each of which executes a portion of the sort or merge 
operation, make up the sort /merge utility program. When you use the com- . 
mand, you do not see the separate subroutines. However, when you include 
these subroutines in a program, you call them one at a time. 


You can call the sort/merge subroutines from any VAX-11 native mode 
language. These include: 


VAX-11 BASIC 
VAX-11 BLISS—32 
VAX-11 COBOL 
VAX-11 COBOL-74 
VAX-11 CORAL-—66 
VAX-11 FORTRAN 
VAX-11 MACRO 
VAX-11 PASCAL 
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You use the same calls from all languages. Calls and associated parameters 
conform to the VAX-11 Calling Standard. (See the VAX_11 Architecture 
Handbook for an explanation of the Calling Standard.) VAX—11 SORT uses 
reference parameters and descriptor parameters for passing data. Because 
different programming languages express these types of parameters differ- 
ently, this chapter does not provide instructions for each language. For 
help, refer to the reference manual or user’s guide for the VAX-11 pro- 
gramming language in which you are writing your program. Unless noted 
otherwise, all parameters described in this chapter are passed by reference. 


Because the subroutines are part of the VAX/VMS Common Run-Time 
Library, they are automatically included in the image when you link. 


This chapter: 


© Provides an overview of SORT and MERGE 


¢ Describes the sort and merge subroutines and their mandatory and 
optional parameters 


¢ Presents sample programs that call the subroutines from native-mode 
languages 


3.1 Two I/O Interfaces 
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You can submit your records for sorting or merging as complete file(s) or as 
single records. These alternatives are called I/O interfaces. 


In file interface your program submits one or more files to SORT or 
MERGE, which creates one sorted or merged output file. In record interface 
your program submits records to the utility one at a time, then receives the 
sorted or merged records one at a time. 


File interface executes faster than record interface and is easier to incorpo- 
rate into your program. If you use it, you must sort (or merge) all records in 
the file(s) and cannot process records before or after sorting. The record 
interface permits you to perform an operation on each record before or after 
sorting or merging. 


If, for example, you want to eliminate duplicate records before merging 
several files, use the record interface. 


The set of calls differs for the two interfaces. After deciding which interface 
you want, select the necessary calls. Section 3.2 describes the sort 
subroutines; Section 3.3 describes the merge subroutines. Figure 3-3 pro- 
vides a summary of subroutines and parameters. 
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3.2 SORT Subroutines 


As with the SORT command, when you call the sort subroutines you must 
provide: 


e Information about keys (for example, data type, size, and position) 
e File specifications of input and output files (for file interface) 


e Instructions about sort method (for example, ascending or descending; 
record, tag, address or index sort) 


You pass this information to SORT by means of the subroutine parameters. 


After being called, each subroutine performs its function and returns con- 
trol to your program. It also returns a 32-bit status code indicating success 
or error in that phase of the sort. Your program can test that value to 
determine success or failure conditions. Programs in most VAX-11 native 
mode languages must declare the subroutines functions in order to do this 
testing. 


When you call sort subroutines from a program, SORT does not provide a 
statistical summary of the operation, as it can when you use the SORT 
command. 


Table 3-1 shows the order of calls for each interface and briefly indicates 
the function of each. Sections 3.2.1 to 3.2.6 describe them in detail. 


Table 3-1: SORT Subroutines 


File Interface 


SOR$PASS__FILES Passes names of input and output files to SORT; must be 
repeated for multiple input files 

SOR$INIT_SORT Passes key information and SORT options 

SOR$SORT_MERGE Sorts the records 

SOR$END__SORT Does. housekeeping functions such as closing files and 


releasing memory 


Record Interface 


SOR$INIT__SORT Passes key information and SORT options 


SOR$RELEASE__REC Passes one input record to the sort; must be called once for 
each record 


SOR$SORT__MERGE Sorts the records 


SOR$RETURN__REC Returns one sorted record to your program; must be called 
once for each record 


SOR$END__SORT Does housekeeping functions such as closing files and 
releasing memory 
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File Interface 


For a sort using file interface, your first step is to pass the input and output 
file specifications to SORT. Call SOR$PASS_FILES and use descriptor 
parameters to pass the file specifications. 


Next, call SOR$INIT__SORT, using its parameters to pass your instruc- 
tions about keys and sort options. Sorting is essentially comparing one key 
with another over and over. You must indicate at this point whether you 
want SORT to do key comparison for you or to use a key comparison routine 
you provide. 


SORT automatically generates the key comparison routine that is most 
efficient for your key data type(s). However, you may want to provide your 
own comparison routine to handle special sorting requirements. For exam- 
ple, you may want a group of records to be placed at the beginning of the 
output file. Or you may want names beginning with “Mc” and “Mac” to be 
placed together. 


Provide SOR$INIT_SORT with a parameter referring it to either the key 
buffer or your key comparison routine. The key buffer contains information 
SORT needs to do the compares, such as number of keys, data type, posi- 
tion, length, and sort order. 


Next, call SOR$SORT_MERGE to execute the sort. It takes no parame- 
ters. Finally, call SOR$;END_SORT to end the sort and release memory. 


Record Interface 


For record interface the first call is SOR$INIT__SORT. As in file interface, 
its parameters define keys and sort options. 


Next, call SOR{RELEASE__REC, passing it a parameter that refers SORT 
to the record buffer in your data area. Your program must call 
SOR$RELEASE_REC once for each record to be released to SORT. 


After your program has passed all records to SORT, it must call 
SOR$SORT__MERGE to perform the sorting. 


Next, you must ask SORT to return the sorted records to your program. Do 
this by calling SOR$RETURN_REC once for each record to be returned. A 
parameter tells SORT where to place the record. 


Finally, call SOR$END_SORT to complete the sort. 


Sections 3.2.1 through 3.2.6 describe each sort subroutine in detail, includ- 
ing its mandatory and optional parameters and the error codes it returns. 


For quick reference, Figure 3-1 gives a flowchart summary of calls and 
parameters. 
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Figure 3-1: Flowchart for SORT Subroutines 


File Interface 





Call SOR$PASS__FILES passing input and output file specification (and out- 
put file options) 
Yes—Multiple input files? Repeat until you have passed file specifications for all 
files 
No, or End 
Call SOR$INIT__SORT passing key buffer address or comparison routine ad- 


dress, and (for non-disk files) Longest Record Length, 
(and sorting options) 


Call SORS$SORT__MERGE 


Call SORSEND__SORT 
Record Interface 


Call SORSINIT__SORT passing key buffer address or compare routine 
address, and Longest Record Length (and sorting 
options) 

Call SOR$RELEASE__REC passing record descriptor 

No—All records released? 


Yes 


Call SOR$SORT__.MERGE 


Call SORSRETURN__REC passing record descriptor (and record size) 
No—All records returned? 
Yes 


Call SOR$END__SORT 


3.2.1 SORS$PASS—FILES 


SOR$PASS__FILES uses two mandatory parameters to pass the names of 
input and output files to SORT. SORT needs these to open input file(s) and 
create an output file for the sorted records. Only file interface calls this 
subroutine. MERGE file interface also calls SOR$PASS_FILES. 


Calling SORT and MERGE from User Programs 3-5 


This subroutine can also accept up to seven optional parameters that pro- 
vide specifications for the output file, such as file organization, format, and 
size. If you do not want default values, you can specify other values. These 
options are like the output file qualifiers of the SORT command 
(see Section 2.1.3). 


The two mandatory parameters are descriptor parameters: 
1. Input file descriptor(s) 
2. Output file descriptor 


When you call SOR$PASS__FILES, you must pass to SORT the file 
specifications of input and output files. For multiple input files, call 
SOR$PASS_FILES once for each input file, passing one input file 
descriptor each time. Specify the output file descriptor only once, as 
part of the first call. 


For example: Call SOR$PASS__FILES(INPUT1,OUTPUT) 
Call SOR$PASS__FILESUINPUT2) 
Call SOR$PASS__FILESUINPUT3) 
Call SOR$PASS__FILES(INPUT4) 


Each file descriptor is a VAX—11 standard string descriptor. It is com- 
posed of two longwords that describe the ASCII string that is the file 
specification of the input or output file. The first word of the first long- 
word contains the length of the ASCII string (SORT does not use the 
second word of the first longword). The second longword contains a 
name that is the address of the string in your program’s data area. 


Some languages, such as FORTRAN , create the descriptor for you. 
Others, such as MACRO, do not. In the sample MACRO program in 
Section 3.9, the name FILEIN is used with the call and refers SORT to 
the input file descriptor. The file descriptor contains the length (10) and 
the address (FILENAMEIN). These refer in turn to the input file speci- 
fication, “RO10SQ.DAT”. 


In the sample FORTRAN program in Section 3.7, OUTPUTNAME is a 
parameter of SOR$PASS_FILES. At other places in the program, 
OUTPUTNAME is defined as 8 ASCII characters and is associated 
with the file specification “TEST.TMP”. Because FORTRAN passes 
CHARACTER quantities by descriptor by default, simply specifying 
OUTPUTNAME in the argument list is the correct way to call 
SOR$PASS__FILES. 


The seven reference parameters that follow are optional. 
3. Output file organization 
Specify a byte containing one of the following values: 


FAB$C_SEQ 
FAB$C_REL 
FAB$C_IDX 


Default value is file organization of the first input file for record or tag 
sort and SEQ for address and index sort. 
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See the $FAB ORG parameter in the VAX-11 Record Management 
Services Reference Manual for information on these options. 


Output file record format 


Specify a byte containing one of the following values: 


FAB$C_FIX 
FAB$C__VAR 
FAB$C__VFC 


Default value is record format of the first input file. 


See the $FAB RFM parameters in the VAX-11 Record Management 
Services Reference Manual for information on these options. 


Output file bucket size 


Specify a byte containing the bucket size. Acceptable values are 1 to 32 
blocks. 


Default value is the bucket size of the first input file if the output file 
organization is the same as the input file organization. If the file organ- 
izations are different, default value is 1 block. 


Output file block size 


Specify an unsigned word containing the block size. Acceptable values 
are 18 to 65,535. 


Use this parameter with magnetic tape files only. Default value is the 
block size established when the file is mounted or, if no size is specified, 
the block size of the input file tape. 


Output file maximum record size 


Specify a word containing the maximum record size for the output file. — 
Acceptable values are 0 to 32,767 (0 to 16,383 for relative files). 


The value 0 means you want no maximum size check; 1 to 32,767 limits 
record size to the specified value. 


See the $FAB MRS parameter in the VAX-11 Record Management. 
Services Reference Manual for more information. 


Output file allocation 


Specify a longword containing the number of blocks you want to allo- 
cate to the output file. Acceptable values are 1 to 4,294,967,295. 


Default value is the number of blocks needed for the output file, based 
on the total input file allocation. 


Output file options 


Specify a longword containing the options you want to place in the 
FAB$L_FOP field. 


See the VAX-11 Record Management Services Reference Manual for an 
explanation of FAB$L_FOP file options. 
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Separate parameters with commas. Also, enter a comma for any parameter 
you skip. However, you can truncate the parameter list at any point. 


Table 38-2 shows the status codes SORT can return to your program after 
completing this phase of the sort. 


Table 3-2: SOR$PASS_FILES: Possible Returns 


SOR$_INCONSIS 1C805C 1867868 Inconsistent data for file 
SOR$_.OPENIN 1C109C 1839260 
SOR$_OPENOUT 1C10A4 1839268 
SOR$_SORT_ON 1C802C 1867820 





































Cannot open input file 





Cannot open output file 












A sort is in progress or this 
call is in the wrong sequence 



















SOR$_VAR_FIX 1C8064 1867876 Cannot change variable 


records to fixed records 









SS$_NORMAL Success 






3.2.2 SORSINIT_SORT 


This subroutine sets up sort work areas and passes parameters that provide 
key specifications and sort options. Both interfaces call it. 


SOR$INIT__SORT accepts eight reference parameters. You must use either 
the key buffer address parameter or the comparison routine address param- 
eter. In addition, for record interface or files not on disk, you must use the 
longest record length parameter. Five other parameters are optional: input 
file size, number of work files, sort type, total key size, and sort options. 


1. Key buffer address 


If you want SORT to do key compares, you must pass the key buffer 
address to SORT. Specify the address of the key buffer in your data 
area. 


In the key buffer, you define the keys by which you plan to sort. You 
must provide information about: 


¢ Number of keys 

© Data type 

¢ Ascending or descending sort 
e Start position 

¢ Length 
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The key buffer is an array of words describing the keys. The first word 
contains the number of keys. Following this word is a block of four 
words for each key. Each block contains: 


e Key type one word giving code for data type (see Table 3-3) 


e Key order one word, 0 or 1, indicating ascending (0) or descend- 
ing (1) sort 


e Start position one word indicating key position (1 to record size) 
e Length one word indicating key length (1-255) 


You can sort by up to ten key fields. Specify keys in the desired sorting 
order, with primary key first and most minor key last. 


Table 3-3: Data Type Codes 


Character 

Binary 

Zoned 

Packed decimal 

Unsigned binary 

Decimal leading overpunched 
Decimal leading separate 
Decimal trailing overpunched 
Decimal trailing separate 

F format floating point 

D format floating point 

G format floating point 

H format floating point 


1 
2 
3 
4 
5 
6 
7 
8 
9 


bud ub te th vob wb ob wea 


For example, suppose that you have a file of records containing a 
40—character name field beginning at position 10 and a 10-digit packed 
decimal field for transaction number beginning at position 60. If you 
want to sort by name as primary key, and transaction number as sec- 
ondary key, set up your key buffer this way: 









number of keys 





= key type (character) 

0 = key order (ascending) 
10 = start position in record 
length of key 


key type (packed-decimal) 
0 = key order (ascending) 
start position in record 

= length of key in digits 







If the key buffer specifies the number of keys as zero, SORT assumes 
that no key buffer has been passed. 


Calling SORT and MERGE from User Programs 3-9 


You do not need this parameter if you provide your own key comparison 
routine. If you pass both key buffer address and comparison routine 
address, SORT ignores the comparison routine address. 


NOTE 


For record interface, you cannot sort decimal] data types 
other than packed decimal unless you provide your own 
key comparison routine. However, you can convert any 
decimal format to packed decimal using the decimal 
instructions in the VAX-11 instruction set. 


Longest record length (LRL) 
Specify a word containing the size of the longest record in the file. 


This parameter is mandatory for record interface and input files not on 
disk. 


Input file size 
Specify a longword containing the input file size in blocks. 


This parameter can increase SORT efficiency in record interface and in 
sorting files not on disk. 


Number of work files 


Specify a byte containing the number of work files you want SORT to 
use in the sorting process. Acceptable values are 0 and 2-10. Default 
value is 2. 


Sort type 
Specify a byte indicating the type of sort you want. 


1 = Record sort 
2 = Tag sort 

3 = Index sort 

4 = Address sort 


Il 


Only file interface using a single input file accepts this parameter. If 
you select record interface or sort multiple files, you can perform only a 
record sort. Default is record sort. 


Total key size 
Specify a byte giving total key size. Acceptable values are 1-255. 
Comparison routine address 


Specify the address of your key comparison routine. SORT calls this 
routine with two reference parameters, the addresses of the two records 
you must compare. The routine must return a 32-bit integer value: 


-1 if key 1 should come before key 2 
0 if keys are equal 
1 if key 1 should come after key 2 


Calling SORT and MERGE from User Programs 


9 


The second FORTRAN program (Section 3.8), for example, uses 
KOMPAR as the address of its comparison routine, then passes the 
( addresses of the two records in this way: 


FUNCTION KOMPAR (REC1»+REC2) 


This parameter is mandatory if you do not use key buffer address. 


Note that you cannot specify your own key comparison routine from 
VAX-11 COBOL-74 or VAX-11 COBOL. 


8. Sort options 


Specify a longword of bit flags containing the options you want to use in 
the sort. Values available in VAX—11 SORT are: 


SOR$V__STABLE _ keeps records with equal keys in order. 


SOR$V__EBCDIC orders ASCII character keys in EBCDIC collating 
C sequence. No translation takes place. 


All other bits in the longword are reserved and must be zero. 


Table 3-4 shows the status codes SORT can return to your program after 
completing this phase of the sort. 


Table 3-4: SOR$INIT__SORT: Possible Returns 


SOR$__BAD__FILE 1C808C 1867916 An invalid file size 

SOR$__BAD__LRL 108084 1867908 An invalid LRL was 
specified 

SOR$__BAD_TYPE 1C806C 1867884 An invalid sort process was 
specified 

SOR$__KEY__LEN 1C80AC 1867948 Invalid key length specified 

¢ SOR$__LRL__MISS 1C8074 1867892 No LRL was specified and is 

required 


SOR$_MISS_KEY 108004 1867780 No key definition specified 
SOR$_NUM_KEY 1C803C 1867836 Invalid number of keys spec- 


ified (must be 1-10) 


SOR$_SORT__ON 1C802C 1867820 A sort is in progress or this 
call is in the wrong sequence 


SOR$__VM__FAIL 1C801C 1867804 SORT failed to get needed 
virtual memory 


SOR$__WORK__DEV 1C800C 1867788 Work file device not random 
access device or not local 
node 


SOR$__WS__FAIL 108024 1867812 SORT failed to get needed 
working set size 


SS$_NORMAL Success 





Calling SORT and MERGE from User Programs 3-11 





3-12 


3.2.3 SORSRELEASE_REC 


In record interface, this subroutine passes a record to SORT. Set up a rec- 
ord buffer in your program’s data area to contain the record. Call 
SOR$RELEASE_REC once for each record to be sorted. 


One descriptor parameter, record descriptor, is mandatory for this call. 
Record descriptor 


When you call SOR$RELEASE_REC, you pass a record to SORT. Use a 
string descriptor that describes your record buffer by its length and its 
address in your program’s data area. Your language may create the 
descriptor for you. 


The record buffer takes a different form depending on whether SORT is 
doing key compares or you are providing your own key comparison routine. 
If you are relying on SORT to do key compares, your record buffer is in 
fact a key-and-record buffer. That is, the record you pass to the 
SOR$RELEASE_REC subroutine consists of the sort keys followed by the 
record itself (including the keys). Specify keys in the same sequence and in 
the same way (for example, the same size and data type) that they appear 
in the key buffer. Leave no space between key fields or between the key 
area and the following record area. 


Thus, for sort compares, record length is equal to the total length of the 
record plus the total length of the key fields. The address is the first byte of 
the first key. 


However, if you are using your own comparison routine, the buffer contains 
only the record itself. The descriptor length is the record length and the 
buffer address is the first byte of the record. 


Table 3-5 shows the status codes SORT can return to your program after 
this phase of the sort. 


Table 3-5: SOR$RELEASE_REC: Possible Returns 


108094 1867924 Invalid descriptor address 
passed 














SOR$_BAD__ADR 




















SOR$_BAD__LRL 108084 1867908 Record length is longer than 


LRL specified 























SOR$_EXTEND 
SOR$_KEY__LEN 
SOR$_MAP 
SOR$_NO__WRK 


1C80A4 
1C80AC 
1C809C 
1C8014 


1867940 
1867948 
1867932 
1867796 


Failed to extend work file 











Invalid key length specified 











Internal sort map error 











Cannot do sort in memory, 
need work files 



















SOR$__SORT_ON 1C802C 1867820 A sort is in progress or this 


call is in the wrong sequence 






SS$_NORMAL Success 
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3.2.4 SORSSORT—MERGE 


This subroutine sorts the file. Call it once after you have passed file names 
or records to SORT and after SOR$INIT_SORT has set up key specifica- 
tions. It takes no parameters. 


Table 3-6 shows status codes returned to your program after this phase of 
the sort. 


Table 3-6: SOR$SORT_MERGE: Possible Returns 


SOR$__BADFIELD 1C10iC 1839132 Bad data in key field 
SOR$_EXTEND 1C80A4 1867940 
SOR$_MAP 1C809C 1867932 
SOR$__NO__WRK 108014 1867796 


























Failed to extend work file 
















Internal sort map error 














Cannot do sort in memory, 
need work files 



















SOR$_READERR 1C10B4 1839236 





Cannot read a specified 
input file record 











SOR$__SORT._ON 1C802C 1867820 A sort is in progress or this 


call is in the wrong sequence 








SOR$__WRITEERR 1C10D4 1839316 Cannot write a specified out- 


put file record 














SS$_NORMAL Success 





3.2.5 SORSRETURN—REC 


This subroutine returns one sorted record to the user program. It places the 
record into a record buffer that you specify. It returns the record length as 
well. MERGE record irterface also calls SOR$RETURN_REC. Call this 
subroutine once for each record sorted or merged. 


SOR$RETURN__REC requires one descriptor parameter, record descriptor, 
and one reference parameter, record size. 


The subroutine returns the SS$__ENDOFFILE status if there are no more - 
records to return. 


1. Record descriptor 


This is a string descriptor that describes the record buffer that receives 
the sorted record. In sorting, this buffer can be the same one from 
which the record was released, but in merging it cannot. 
SOR$RETURN__REC also accepts a dynamic string descriptor for this 
parameter. 


Before SORT returns the record, it strips off the leading keys from the 
key-and-record configuration used for SORT key compares. The length 
removed is the value specified as total key size to SORSINIT__SORT. 
The returned record, therefore, is equal to either (1) the record passed 
with the user compare routine or (2) the record portion of the key-and- 
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record buffer used for SORT key compares. The length you specify in 
the record descriptor is the length of your record only. The address is 
that of the first byte of the record. 


2. Record size 


Specify a word that receives the actual length of the returned record. 


Table 3-7 shows status codes returned to your program at the end of this 
phase of the sort. . 


Table 3—7: SOR$RETURN_REC: Possible Returns 


SOR$_BAD_LRL 108084 1867908 Record length is longer than 
LRL specified 











































SOR$_BAD__ORDER 
SOR$_EXTEND 
SOR$_MAP 
SS$_ENDOFFILE 


1C80D4 
1C80A4 
1C809C 
870 


1867988 
1867940 
1867932 

2160 


Input file UL is out of order 












Failed to extend work file 











Internal sort map error 











Success, no more records to 
return 






Success, a record has been 
returned 


SS$_NORMAL 








3.2.6 SORSEND__SORT 


This subroutine closes files, cleans up sort work areas, and releases mem- 
ory. It takes no parameters. Call SOR$END_SORT once to end the sort. 
You cannot begin another sort operation before calling this subroutine. 


Table 3-8 shows status codes returned at the completion of the sort. 


Table 3-8: SOR$END_SORT: Possible Returns 


1C80B4 1867908 Failed to delete work files 
1 1 











SOR$_CLEANUP 












and data areas 






SS$_NORMAL Success 


3.3 MERGE Subroutines 
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and reinitialize work areas 
When you call the merge subroutines, you must provide: 
* Number of input files 
* File specifications of input and output files (for file interface) 
¢ Information about merge keys 


¢ Input routine (for record interface) 
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You pass this information to MERGE by means of the subroutine 
parameters. 


After performing its function, each subroutine returns to your program a 
32-bit status code indicating success or error in that phase of the merge. 
Your program can then test that value to determine success and failure 
conditions. Programs in most VAX-11 native mode languages must declare 
the subroutines’ functions in order to do this testing. 


Table 3-9 shows the order of calls for each interface and briefly indicates 
the function of each. Since sorting involves merging, MERGE uses some of 
the SORT subroutines. It also uses two other subroutines, described in 
Sections 3.3.1 and 3.3.2. 


Table 3-9: MERGE Subroutines 


File Interface 


SOR$PASS__FILES Passes names of input and output files to MERGE; called 












once for each input file 
SOR$INIT_MERGE Sets up key parameters 
SOR$DO__MERGE Does the merge and cleans up 
Record Interface 
SORSINIT_MERGE Sets up key parameters and calls input routine 
SOR$RETURN__REC Returns merged records and continues to call input 







routine; called once for each record 





SOR$END_SORT 





Cleans up 






File Interface 


For a merge using file interface, your first step is to pass the input and 
output file specifications to MERGE. Call SOR$PASS__FILES and provide 
it with the file specifications. 


You can merge from 2 to 10 input files; call SOR$PASS__FILES once for 
each file. Pass the file specification for the one merged output file in the 
first call. 


Next, call SORT$INIT_MERGE, using its parameters to pass your 
instructions about keys and merge options. Just as in sorting, merging 
involves comparing one key with another over and over. You can allow 
MERGE to do key comparison for you or provide your own comparison 
routine tailored to your data. Provide a parameter referring 
SOR$INIT_MERGE to either your key buffer or your key comparison 
routine. 


Next, call SOR$DO__MERGE. This subroutine executes the merge and 
cleans up. 
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Record Interface 


For record interface, first call SORS$INIT_-MERGE. As in file interface, its 
parameters define keys and merge options. It also issues the first call to 
your input routine, which begins releasing records to the merge. 


Next, call SOR5RETURN__REC. It returns a merged record and continues 
to call the input routine. In merging, unlike sorting, MERGE does not need 
to hold all records before it can begin returning them in the desired order. 
Releasing, merging, and returning of records are all taking place in this 
phase of the merge. 


Call SOR$SRETURN_REC until all records have been returned. A parame- 
ter tells MERGE where to place the merged record. 


Finally, call SOR$END_SORT to clean up. 


Sections 3.3.1 and 3.3.2 describe the merge subroutines. For quick refer- 
ence, Figure 3—2 gives a flowchart summary of calls and parameters. 


Figure 3-2: Flowchart for MERGE Subroutines 


File Interface 





Call SOR$PASS__FILES passing input and output file descriptors (and output 
file options) 


No—All input file descriptors passed? 


Ke 

Call SORSINIT_MERGE passing merge order, and key buffer address or com- 
parison routine address, and (for non-disk files) LRL 
(and merge options) 


Call SOR$D0__MERGE 
Record Interface 


Call SORSINIT_MERGE passing merge order, input routine address, LRL, and 
key buffer address or comparison routine address (and 
merge options) 

Call SOR$RETURN__REC passing record descriptor (and record size) 

No—All records returned? 


Yes 


Call SORSEND__SORT 
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3.3.1 SORSINIT_MERGE 


This subroutine accepts parameters that provide key specifications and 
merge options and tell MERGE the number of input files. Both interfaces 
call it. 


SORS$INIT__MERGE accepts six reference parameters. You must always 
specify merge order. In addition, you must specify either key buffer address 
or comparison routine address. For record interface, you must also pass 
input routine address and longest record length. Finally, for files not on 
disk, you must pass longest record length. An optional parameter contains 
merge options. 


1. 


Merge order 


Specify a byte containing the number of input files (2-10). Merge order 
is a mandatory parameter in all merge operations. 


Key buffer address 


Specify the address of your key buffer array. Set up the key buffer array 
in the same way as for SOR$INIT__SORT. 


This parameter is mandatory unless you are using comparison routine 
address. 


Longest record length (LRL) 


Specify a word containing the size of the longest record in any of the 
input files. 


This parameter is mandatory for record interface and for non-disk files. 
Merge options 


Specify a longword of bit flags containing the options you want for the 
merge. Values available are: 


SOR$V__EBCDIC Merges ASCII character keys in the EBCDIC 
collating sequence. Does not translate charac- 
ters. 


SOR$V_SEQ_CHECK Requests an “out of order” error return if an 
input file is not in correct order. 


All other bits in the longword are reserved and must be zero. 
Comparison routine address 


Specify the address of your key comparison routine. Set up this routine 
in the same way as for SORT$INIT_SORT. 


This parameter is mandatory if you do not use key buffer address. 
Input routine address 


Specify the address of a routine you write to release a record to the 
merge. SOR$INIT_MERGE and SOR$RETURN_REC call this rou- 
tine until all records have been passed. 
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Your routine must read (or construct) a record, place it in a record 
buffer, store its length in an output parameter, then return control. 
MERGE compares keys and returns records in merged order until it has 
processed all records. The input routine must accept three parameters 
and return a status value. The parameters provide for receiving and 
storing information necessary to the merge operation, such as the next 
file from which to read a record. Use the following parameters with 
your input routine. 


e A descriptor for the buffer where your routine must place the record. 


e A longword (passed by reference) containing the file number from 
which to input a record. The first file is 1, the second 2, and so on. 


e A word (passed by reference) where your routine must return the 
actual length of the record. 


Your routine must return a status value. If you return SS$__NORMAL 
(or any other success status), the merge continues, using the record that 
you released. If you return SS$__ENDOFFILE, MERGE notes that you 
have no more records for the file specified by parameter 2, and ignores 
the contents of the record buffer. If you return any other error status, 
MERGE terminates and passes the status value back to the caller of 
SOR$INIT__MERGE or SOR$RETURN_REC. 


The second FORTRAN program (Section 3.8), for example, specifies an 
input routine in this way: 


FUNCTION READ_REC (RECX, FILE, SIZE) 
You must use this parameter in a merge using record interface. 


Table 3-10 shows the status codes returned to your program after this 
phase of the merge. 


Table 3-10: SORS$INIT__MERGE: Possible Returns 


SOR$__BAD_KEY 108034 1867828 Invalid key specification 
SOR$__BAD_.MERGE 1C80BC 1867964 














Merge order must be 
between 2 and 10 © 









1C80AC 
1C8074 


1867948 
1867892 









SOR$_KEY__LEN 
SOR$_LRL_MISS 






Invalid key length specified 











No LRL was specified and is 
required 

















1867780 
1867836 


SOR$_MISS_KEY 
SOR$_NUM_KEY 


1C8004 
1C803C 


No key definition specified 














Invalid number of keys 
specified (must be 1-10) 
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Table 3-10: SOR$INIT_MERGE: Possible Returns (Cont.) 


SOR$_SORT__ON 1C802C 1867820 A sort or merge is in prog- 
ress or this call is in the 
wrong sequence 


SOR$_VM_FAIL 1C801C 1867804 MERGE failed to get needed 





virtual memory 


SS$_NORMAL Success 


3.3.2 SOR$DO__MERGE 
This subroutine performs the merge and cleans up. It takes no parameters. 


Table 3-11 shows the status codes returned to your program at the end of 
the merge. 


Table 3-11: SOR$DO__MERGE: Possible Returns 


SOR$__CLEAN__UP 1C80B4 1867908 Failed to delete work files 
and reinitialize work areas 
and data areas 


SOR$__READERR 101084 1839236 Cannot read a_ specified 
input file record 


SOR$__WRITEERR 1C10D4 1839316 Cannot write a specified out- 
put file record 


SS$_NORMAL Success 





Figure 3-3 provides a summary of sort and merge subroutines and parame- 
ters. It indicates the place of each subroutine in sort/merge and in record/ 
file interface, and it labels each parameter as reference or descriptor and as 
mandatory or optional. 


Sections 3.4 to 3.11 contain sample programs calling the sort and merge 
subroutines from VAX-~11 native mode languages. 


In VAX-11 COBOL, you can execute a sort or merge with the SORT or 
MERGE statement, so no sample COBOL program is given here. You can, 
however, use the calls described in this chapter with VAX-11 COBOL and 
COBOL-74, and sort programs already written in COBOL-74 can be 
moved to VAX-11 COBOL. See Chapter 11 in the VAX-11 COBOL User’s 
Guide for an explanation of using the COBOL SORT and MERGE verbs. 
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Figure 3-3: Subroutine Summary 


Call Order 
SORT MERGE Subroutine 
FIR FIR 
IIE IIE 
LIC LIC 
E E 
1 1 SOR$PASS__FILES 
2/1 SORSINIT__SORT 
2 SOR$RELEASE__REC 
343 SOR$SORT_.MERGE 
4 2 SOR$RETURN__REC 
4|5 3 SORSEND__SORT 
2}1 SORSINIT__MERGE 
3 SOR$DO__MERGE 
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Parameter 


. Input file descriptor 
. Output file descriptor 


. Output file organization 
. OP file record format 

. OP file bucket size 

. OP file block size 

. OP file max record size 
. OP file allocation 

. OP file options 


. Key buffer address 


2. LRL 


ANON W 


t, 


. Input file size 

. Number of work files 
. Sort type 

. Total key size 

. Comparison routine address 
. Sort options 


Record descriptor 


None 


1. 
2. 


Record descriptor 
Record size 


None 


1. 
2. 
3. 


4. 
5. 
6. 


Merge order 
Key buffer address 
LRL 


Merge options 


Comparison routine address 


Input routine address 


None 
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Mandatory/ 
Optional 


OO00000 Fes 


M:1o0r7 
M for record & 
non-disk files 


== 


M 
M:2or5 
M for record & 
non-disk files 
(6) 
M:2or5 
M:record 


Reference/ 
Descriptor 


Oo0 


DD DVDVDIDIWDIDIDV 


DVDVDDDV 


oO 


nvDD 


3.4 Sample VAX-11 BASIC Program (SORT) 


100 
\ 
\ 
\ 
\ 
\ 


200 


EXTERNAL INTEGER FUNCTION SORSINIT_SORT &. 
EXTERNAL INTEGER FUNCTION SOR$RELEASE_REC g. 
EXTERNAL INTEGER FUNCTION SORSSORT_MERGE &. 
EXTERNAL INTEGER FUNCTION SORSRETURN_REC &. 
EXTERNAL INTEGER FUNCTION SORSEND_SORT & 
EXTERNAL INTEGER CONSTANT SS$_ENDOFFILE 
MAP (KEYB) KEY$=8» REC$=32, WORD KEY_BUF(4) 8. 
MAP (KEYB) KEY_AND_REC$=40 
KEY.-BUF(O%) = 1% ! One key &. 
KEY_BUF(1%) = 1% ! Character Key type &. 
KEY_BUF(2%) = 0% ! Ascending order 8. 
KEY_BUF(3%) = 1% ! Starting Position &. 
KEY_BUF(4%) = 8% ! Size of Key 
SORT_STATUS% = SORSINIT_SORT(KEY_BUF(0%)» 32%) 
IF (SORT_STATUSZ AND 1%) = O% &. 
THEN PRINT “Error in INIT_SORT:"3 SORT_STATUS% 8. 
GOTO 32767 
FOR I% = 1% TO 10% 
RECS = STRING$(32%, 65% + (26, * RND)) 
KEY$ = RECS 
PRINT KEY$ 
SORT_STATUS% = SORSRELEASE_REC(KEY_AND_REC$) 
IF (SORT_STATUS% AND 1%) = 0% &. 
THEN PRINT "Error in RELEASE_REC:"3 SORT_STATUSY% & 
GOTO 32767 
NEXT 1% 
SORT_STATUS%Z = SOR$SSORT_MERGE 
IF (SORT_STATUS% AND 1%) = 0% 8. 
THEN PRINT "Error in SORT_MERGE:"$ SORT_STATUS% 8&8 
GOTO 32767 
PRINT "Starting release" 
RECS = "“KHHHHHHHEHHH" 
WHILE -1% 
SORT_-STATUS% = SORSRETURN_REC(REC$>LCL%) 
IF (SORT_STATUS% AND 1%) = 0% & 
THEN IF SORT_STATUS% <> SS$ENDOFFILE .- &. 
THEN PRINT “Error in RETURN_REC:"3 SORT_STATUS% & 
GOTO 32767 & 
ELSE GOTO 32767 
PRINT RECS 
NEXT 


SORT_STATUS% = § 
IF (SORT_STATUS% AND 1%) = 0% & 
THEN PRINT "E 


END 


ORSEND_SORT 


rror in END_SORT:"$3 SORT_STATUS% 
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3.5 Sample VAX-11 BASIC Program (MERGE) 


100 ! 
! This program demonstrates the BASIC calling sequences 

! for the merge RECORD interface, 

| 

EXTERNAL INTEGER FUNCTION SORSINIT_MERGE+ SORSRETURN_REC 

\ EXTERNAL INTEGER CONSTANT SS$_ENDOFFILE 

\ EXTERNAL INTEGER READ_REC+ KOMPAR 

\ MAP (RECBUF) STRING REC=80 

\ MAP (OUTBUF) STRING REC2=80 

\ COM (FILES) LONG ORDER» FILTAB(10) 


300 ORDER = 4% 
\ FILTAB(I%) = I% FOR I% = 1% TO ORDER 
400 ! 
! First open all the input files, Share the record buffer, 
! 
OPEN "A.DAT" FOR INPUT AS FILE #FILTAB(1%)+ SEQUENTIAL FIXED 8. 
» ACCESS READ» MAP RECBUF 
\ OPEN "B.DAT" FOR INPUT AS FILE #FILTAB(2%) + SEQUENTIAL FIXED &. 
» ACCESS READ» MAP RECBUF 
\ OPEN "C.DAT" FOR INPUT AS FILE #FILTAB(3%)» SEQUENTIAL FIXED 8 
» ACCESS READ» MAP RECBUF 
\ OPEN "D.DAT" FOR INPUT AS FILE #FILTAB( 4%)» SEQUENTIAL FIXED g. 


» ACCESS READ» MAP RECBUF 
500 


record length» the compare routine address» and the 


! 
! Initialize the merge, Pass the merge order», the largest 
1 
! inPut routine address, 


| 
SYS_-STATUS% = SORSINIT_MERGE (ORDER 10% »80%5 +KOMPAR »READ_REC) 

\ CALL SYS$EXIT(SYS_STATUS% BY VALUE) & 
IF (SYS_STATUS% AND 1%) = O% 


600 ! 
! Now loop getting merged records. SOR$RETURN_REC will 

! call READ_REC when it needs input, 

1 


SYS_STATUS% = SOR$RETURN_REC (REC2+LENGTH%) 


\ GOTO 700 IF SYS_STATUS% = SS$_ENDOFFILE 
\ PRINT SEG$(REC2+1%»LENGTH%) 

\ GOTO 600 

700 ! 


' Now tell SORT that we are all done. 
! 


SYS_STATUSZ = SORSEND_SORT 
\ CALL SYS$EXIT(SYS_STATUS% BY VALUE) & 
IF (SYS_STATUS% AND 1%) = 0% 


900 END 
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1000 


FUNCTION INTEGER READ_REC(STRING RECX+s INTEGER FILEX:» SIZE) 


RECX.wl 


i 
! 
1 
! 
! 
! 
! 
! 
\ 
I 
I 
! 
! etc, 
! 

! 

! 

! 


This routine reads a record from one of the input files 
for merging. It will be called by SORSINIT_MERGE and by 
SORS$RETURN_REC. 

Parameters: 


sds Buffer to hold the record after it 


is read in. 


FILE.rlor Indicates which file the record is 
to be read from, 1 specifies the 
first files 2 specifies the second 


LENGTH.wl.r Is the actual number of bytes in 
the record, This is set by READ_REC 


ON ERROR GOTO 1900 


EXTERNAL INTEGER CONSTANT SS$_ENDOFFILE+s SS$_NORMAL 


MAP (RECBUF ) 
COM (FILES) 


STRING REC=80 


INTEGER ORDER» FILTAB(10) 


READ_REC = SS$_ENDOFFILE 


IF (FILEX ¢ 


1%) OR (FILEX > ORDER) THEN FUNCTIONEXIT 


GET #FILTAB(FILEX) 


RECX = REC 


SIZE = RECOUNT 
READ_REC = SS$_ NORMAL 


FUNCTIONEXIT 


' Here if end of file. 


RESUME 1910 


READ_REC = SS$_ENDOFFILE 


FUNCT IONEND 


FUNCTION INTEGER KOMPAR(STRING REC1=20 BY REF» REC2=20 BY REF) 


This routine compares two records. It returns -1 


1 
! 

! if the fi 
! O if the 

! record is 
| 

KOMPAR = 0% 

FUNCTIONEXIT 


KOMPAR = -1% 
FUNCTIONEXIT 


KOMPAR = 1% 
FUNCT IONEND 


rst record is smaller than the second, 
records are equals and 1 if the first 
larger than the second. 


IF RECi = REC2 


IF REC1 ¢ REC2 
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3.6 Sample VAX-11 BLISS-32 Program (SORT) 


MODULE TESTSUB (MAIN = FILEIO, 
LANGUAGE (BLISS32) , 
IDENT = ‘XO1,01 ° 
) = 

BEGIN 

! 


|! ENVIRONMENT: STARLET OPERATING SYSTEM, USER MODE UTILITY 


FORWARD ROUTINE 
CREATE_OQUTPUT, 
OPEN_FILE» 
OPEN_INPUT, 
CLOSE_FILE,» 
GET_RECORD, 
PUT_RECORD » 
RAB_INIT+ 
OUT_RAB_INIT$ 


LIBRARY ‘SYS$LIBRARY:STARLET,L32°3 
BIND 


FILENAMEIN = UPLIT BYTE(ZASCII‘RO10SQ.DAT’)» 
FILENAMEOUT = UPLIT BYTE(%ASCII’TEST.TMP’) 3 


LITERAL 
ERROR = O, 
SUCCESS = 1, 
RECORD_SIZE = 80, ' Max record size 
KEY_SIZE = 103 ! Size of Key field, 
OWN 
COM_FAB : $FAB_DECL» 'FAB 
COM_RAB : $RAB_DECL» 'RAB 
OUT_FAB : $FAB_DECL, !OUTPUT FAB 
OUT_RAB : $RAB_DECL», 'QUTPUT RAB 
FILEIN : YECTOR (2] INITIAL (10+ FILENAMEIN) » 
FILEOQUT : VECTOR [2] INITIAL (8+ FILENAMEOQUT) » 
OUTSIZ, 
KEYBUF : WORD INITIAL (1) 
KEYTYP 3 


’ 
WORD INITIAL (1), 
KEYORD : WORD INITIAL (0), 

KEYPOS : WORD INITIAL (1)>»% 

KEYSIZ : WORD INITIAL (KEY_SIZE), 

INLRL : WORD INITIAL (KEY_SIZE + RECORD _SIZE), 
WRKFILE : INITIAL (500), 

NUMWRK : BYTE INITIAL (4), 

BUFFER : VECTOR CRECORD_SIZE + KEY_SIZE, BYTE]} 


BIND 
KEYAREA = BUFFER [CO] : VECTOR CKEY_SIZE,» BYTE], 
RECORDBUF = BUFFER CKEYSIZE] : VECTOR CRECORD_SIZE,> BYTE]$ 
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OWN 


RECDESC : VECTOR (C2) INITIAL 


EXTERNAL ROUTINE 
SOR$SPASS_FILES» 
SORSINIT_SORT» 
SORSSORT_MERGE » 
SORSRELEASE_REC» 
SORSRETURN_REC, 
SORSEND_SORT 5 


GLOBAL ROUTINE FILEIO : 
BEGIN 


LOCAL 
ERRORCODE 5 


! TRY RECORD 1/0 
IF NOT OPEN_INPUT () 


IF NOT RAB_INIT (0) 
OUT_RAB_INIT ()5 


IF NOT SORSINIT_SORT 
WHILE 1 DO 
BEGIN 
CH$FILL (’ 


(KEYBUF » 


‘y RECORD_SIZE, CH$PTR 
ERRORCODE = GET_RECORD 


(KEY_SIZE + RECORD_SIZE» KEYAREA) 3 


THEN RETURN ERRORS$ 
THEN RETURN ERRORS 


INLRL»> WRKFILE» NUMWRK ) 


' Fill record with blanks. 
(RECORDBUF)) 3 


()5 ! Read a record. 


IF .ERRORCODE EQL RMS#_EOF THEN EXITLOOPS 


IF NOT 


CHSMOVE 


»-ERRGRCODE THEN RETURN 


»*ERRORCODES 
! Extract the Key. 


(KEY_SIZE» CHS$PTR(RECORDBUF) » CHSPTR(KEYAREA) ) 3 


' Pass the record to SORT 
ERRORCODE = SOR$RELEASE_REC (RECDESC) 5 
IF NOT .ERRORCODE THEN RETURN .ERRORCODES 
END$ 
ERRORCODE = SORS$SORT_MERGE ()35 ' Sort the records, 


IF NOT 


WHILE 1 DO 
BEGIN 


ERRORCODE = SORSRETURN_REC 


+ERRORCODE THEN RETURN 


+ERRORCODE 5 


' Retrieve a sorted record 
(RECDESC, OUTSI2Z)35 


IF .ERRORCODE EQL SS$_ENDOFFILE THEN EXITLOOPS 


PUT_RECORD (.OUTSIZ» KEYAREA) 3 ! 


END$ 


ERRORCODE = SORSEND_SORT ()3 ! 


Copy to output file, 


Clean up. 


IF NOT .ERRORCODE THEN RETURN .ERRORCODE 5 


CLOSE_FILE 
SUCCESS 
END 


(1)5 


THEN RETURN ERROR? 
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ROUTINE OPEN_INPUT 


! FUNCTIONAL DESCRIPTION: 
! FILE AND 
! FORMAL PARAMETERS: 

\ NONE 

! IMPLICIT INPUTS: 

! NONE 

! IMPLICIT OUTPUTS: 

! NONE 

! ROUTINE YALUE: AN ERROR 
! COMPLETION CODES: 1 FOR 
' SIDE EFFECTS: THE INPUT 
\ 


BEGIN 

LITERAL 
DEFAULT_SIZE 
KEY_BUCKET = 
TOTAL_KEY = 3 

BIND 


DEFAULT_TYPE 


! INITIALIZE THE FAB 


15 
3 


THIS ROUTINE SETS UP THE FAB FOR THE INPUT 
CALLS THE COMMON OPEN ROUTINE. 


CODE ON ERROR 
SUCCESS 
FILE NAME IS PARSED AND THE FILE OPENED 


4+ !DEFAULT TYPE SIZE 
* I!OVERHEAD IN INDEX BUCKET 
‘OVERHEAD IN TOTAL KEY SIZE 


UPLIT BYTE(“ASCII’.DAT’)5$ 


$FAB_LINIT (FAB = COM_FAB» FNA = CH$PTR (FILENAMEIN) + 


FNS = 10% DNA = 
DNS = DEFAULT_SIZE 
IF NOT OPEN_FILE ( 
CREATE_OUTPUT () 
END§ 


ROUTINE RAB_INIT (LRL) : 
b+4+ 


FUNCTIONAL DESCRIPTION: 
FILE AND 


CHS$PTR (DEFAULT_TYPE) » 
» FOP = SQO+s RAT = CR)$ 
) THEN RETURN ERROR; 


THIS ROUTINE SETS UP THE RAB FOR THE INPUT 
CONNECTS. 


FORMAL PARAMETERS: THE LONGEST RECORD LENGTH 


IMPLICIT INPUTS: 
NONE 


NONE 


ROUTINE VALUE: THE TOTAL NEEDED BUFFER SIZE» OR AN ERROR CODE. 


COMPLETION CODES: 
SIDE EFFECTS: 


! 
| 
! 
! 
' 
! 
! IMPLICIT OUTPUTS: 
| 
! 
t 
! 
! 


BEGIN 


! IF AN INDEX SORT CREATE 
! INITIALIZE THE RAB 


THE OUTPUT FILE NOW THAT WE KNOW THE KEY SIZE. 


$RAB_LINIT (RAB = COM_RAB, FAB = COM_FABy RAC = SEQ, KRF = 0, 
UBF = RECORDBUF, USZ = RECORD_SIZE» ROP = RAH) 
IF NOT $RMS_CONNECT (RAB = COM_RAB) THEN RETURN ERROR} 


SUCCESS 
END$ 
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ROUTINE CREATE_OUTPUT 


I++ 
FUNCTIONAL DESCRIPTION: 
FILE AND 
FORMAL PARAMETERS: NONE 
IMPLICIT INPUTS: 
NONE 


NONE 
ROUTINE VALUE: AN ERROR 
COMPLETION CODES: 1 FOR 


THIS ROUTINE SETS UP THE FAB FOR THE OUTPUT 
CREATES IT. 


CODE ON ERROR. 
SUCESS» 


SIDE EFFECTS: THE QUTPUT FILE NAME IS PARSED AND THE FILE CREATED. 


! 
! 
I 
\ 
! 
! IMPLICIT OUTPUTS: 
! 
! 
! 
! 
! 


BEGIN 


! INITIALIZE THE FAB 


$FAB_INIT (FAB = OUT_FAB» FAC = PUT» FNA = CHSPTR (FILENAMEQUT) » 


FNS = 8)5 


| DEFAULT TO INPUT FILE ORGANIZATION, RECORD FORMAT AND ATTRIBUTES. 


OUT_FAB CFABSB_ORG] 
OUT_FAB CFABSB_RFM] 
OUT_FAB CFABSB_RAT] 


! FINALLY CREATE THE FILE 


IF NOT $RMS_CREATE (FAB = OUT_FAB) 


THEN 

RETURN ERRORS 
SUCCESS 
END$ 


ROUTINE OUT_RAB_INIT =: = 


l++ 
FUNCTIONAL DESCRIPTION: 
FILE AND 


! 

| 

! 

! FORMAL PARAMETERS: NONE 
! IMPLICIT INPUTS: 

! NONE 

! IMPLICIT OUTPUTS: 

| NONE 

! ROUTINE VALUE: 

! COMPLETION CODES: ERROR 
! SIDE EFFECTS: 

| 


BEGIN 


»COM_FAB CFABSB_ORGI5 
+COM_FAB CFABSB_RFMI5 
»COM_FAB CFABSB_RATI3$ 


+ 


'CREATE OR OPEN FILE 


THIS ROUTINE SETS UP THE RAB FOR THE OUTPUT 
CONNECTS. 


CODE ON ERROR OR SUCCESS 


! INITIALIZE THE RAB BASED ON SORT TYPE AND FILE ORGANIZATION 


$RAB_INIT (RAB = OUT_RAB» KRF = O» RAC = SEQ» ROP = WBH» FAB = OUT_FAB)$ 
IF NOT $RMS_CONNECT (RAB = QUT_RAB) THEN RETURN ERRORS 


SUCCESS 
END$ 
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ROUTINE OPEN_FILE : = 


FUNCTIONAL DESCRIPTION: THIS ROUTINE CALLS THE RMS FILE NAME PARSER 


AND OPENS THE FILE, 


FORMAL PARAMETERS: NONE 
IMPLICIT INPUTS: 
NONE 
IMPLICIT OUTPUTS: 
NONE 
ROUTINE VALUE: 


COMPLETION CODES: 1 FOR SUCCESS, 0 FOR ERROR 


BEGIN 


IF NOT $RMS_OPEN (FAB = COM_FAB) 


SUCCESS 
END$ 


ROUTINE GET_RECORD : = 


++ 


THEN RETURN ERROR} 


FUNCTIONAL DESCRIPTION: THIS ROUTINE CALLS THE RMS GET RECORD ROUTINE 
TO READ A RECORD FROM A FILE, 


FORMAL PARAMETERS: NONE 


IMPLICIT INPUTS: THE FAB AND RAB ALREADY INITIALIZED FOR THE 


APPROPRIATE FILE. 
IMPLICIT QUTPUTS: 
NONE 
ROUTINE VALUE: THE ADDRESS OF THE 
COMPLETION CODES: AN RMS ERROR 


RECORD DESCRIPTOR» OR AN EOF STATUS. 


SIDE EFFECTS: IF AN ERROR OCCURS A MESSAGE IS SENT TO THE USER, 


BEGIN 


' GET RECORDS UNTIL EITHER A RECORD IS READ OR END OF FILE IS REACHED. 


PRINT A WARNING MESSAGE FOR EVERY 


READ ERROR THAT OCCURS. 


= COM_RAB) OF 
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WHILE 1 DO 
SELECTONE $RMS_GET (RAB 
SET 
CRMS$_EOF] 
BEGIN 
CLOSE_FILE (0)$ 
RETURN RMS$_EOF$ 
END$ 
CRMS$_SUC] : 
IF ,.COM_RAB CRAB$W_RSZ] NEQ O 
THEN 
RETURN SUCCESS$ 
COTHERWISE] : 
RETURN ERROR$ 
TES$ 
SUCCESS 
END$ 
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ROUTINE PUT_RECORD (LEN» ADR) =: = 


ROUTINE CLOSE_FILE (OUTPUT_FLAG) : 


++ 

FUNCTIONAL DESCRIPTION: THIS ROUTINE CALLS THE RMS PUT RECORD ROUTINE 

TO WRITE A RECORD TO A FILE. 
FORMAL PARAMETERS: THE LENGTH AND ADDRESS OF THE RECORD 
IMPLICIT INPUTS: THE FAB AND RAB ALREADY INITIALIZED FOR THE 
APPROPRIATE FILE. 
IMPLICIT OUTPUTS: 
NONE 

ROUTINE VALUE: 

COMPLETION CODES: NONE 

SIDE EFFECTS: IF AN ERROR OCCURS A MESSAGE IS SENT TO THE USER. 


BEGIN 
PUT THE RECORD INTO THE OUTPUT FILE. 


OUT_RAB CRABSL_RBFJ +ADRG 

OUT_RAB CRABSW_RS2Z] «LENS 

IF NOT $RMS_PUT (RAB = OUT_RAB) THEN RETURN ERRORS 
SUCCESS 

END$ 


++ 


FUNCTIONAL DESCRIPTION: THIS ROUTINE DISCONNECTS AND CLOSES A FILE. 


FORMAL PARAMETERS: A FLAG INDICATING WHETHER TO CLOSE THE OUTPUT FILE» 
AS WELL AS THE INPUT FILE OR DELETE IT. 
IMPLICIT INPUTS: THE RAB AND FAB INITIALIZED FOR THE APPROPRIATE 
FILE. 

IMPLICIT OUTPUTS: 

NONE 
ROUTINE VALUE: 
COMPLETION CODES: NONE 
SIDE EFFECTS: IF AN ERROR OCCURS A MESSAGE IS SENT TO THE USER. 


BEGIN 

LITERAL 
CLOSE_IN = OF 
CLOSE_BOTH = 1» 
DELETE_OUT = 23 


BASED ON THE OUTPUT FLAG EITHER CLOSE THE OUTPUT FILE AND THE INPUT 
FILE» CLOSE THE INPUT FILE OR CLOSE THE INPUT FILE AND DELETE THE 
OUTPUT FILE. RETURN ANY ERRORS. 


IF NOT .OUTPUT_FLAG 


THEN 
BEGIN 
IF NOT $RMS_DISCONNECT (RAB = COM_RAB) THEN RETURN ERRORS 
IF NOT $RMS_CLOSE (FAB = COM_FAB) THEN RETURN ERRORS 
END$ 
IF .OUTPUT_FLAG 
THEN 
BEGIN 


IF NOT $RMS_DISCONNECT (RAB = OUT_RAS) THEN RETURN ERRORS 
IF NOT $RMS_CLOSE (FAB = OUT_FAB) THEN RETURN ERRORS 
END 
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ELSE 
IF .OUTPUT_FLAG EQL DELETE_OUT 


THEN 
IF NOT $RMS_ERASE (FAB = OUT_FAB) THEN RETURN ERROR} S) 
SUCCESS 


END$ 
END 


ELUDOM 
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3.7 Sample VAX-11 FORTRAN Program (SORT) 


PROGRAM CALLSORT 


THIS IS A SAMPLE FORTRAN PROGRAM THAT CALLS THE 

NATIVE SORT SUBROUTINE PACKAGE USING THE FILE I/O INTERFACE. 
THIS PROGRAM REQUESTS AN INDEX SORT OF FILE ‘RO10SQ.DAT’ 
INTO THE FILE ‘TEST.TMP’. THE KEY IS AN 80 BYTE CHARACTER 
ASCENDING KEY STARTING IN POSITION ONE OF EACH RECORD, 


DEFINE EXTERNAL FUNCTIONS AND DATA 


anNnnnnnnnann 


CHARACTER*10 INPUTNAME ! INPUT FILE NAME 
CHARACTER*8 OUTPUTNAME !QUTPUT FILE NAME 

INTEGER*#2 KEYBUF(S) !KEY DEFINITION BUFFER 
INTEGER*¥2 NUMWRK ! NUMBER OF WORK FILES 

INTEGER*2 ISRTTYP !SORT PROCESS 

INTEGER*#4 SOR$SPASS_FILES !SORT FUNCTION NAMES 
INTEGER*4 SORSINIT_SORT 

INTEGER*4 SORSSORT_MERGE 

INTEGER#4 SORSEND_SORT 

INTEGER#4 ISTATUS !STORAGE FOR SORT FUNCTION VALUE 


INITIALIZE DATA - FIRST THE FILENAMES THEN THE KEY BUFFER FOR 
ONE 80 BYTE CHARACTER KEY STARTING POSITION 1+ 3 WORK FILES 
AND AN INDEX SORT PROCESS 


ononnn 


DATA INPUTNAME s;OUTPUTNAME / ‘RO10SQ,.DAT’+’TEST.TMP’ / 
DATA KEYBUF »NUMWRK sISRTTYP/ 1919091 18013537 


CALL THE SORT EACH CALL IS A FUNCTION 


PASS SORT THE FILENAMES 


onnnaInin 


ISTATUS = SOR#SPASS_FILES( INPUTNAME »sOUTPUTNAME ) 
IF (.NOT. ISTATUS) GOTO 19 


INITIALIZE WORK AREAS AND KEYS 


ann 


ISTATUS = SORSINIT_SORT(KEYBUF »»+ »NUMWRK + ISRTTYP) 
IF (.NOT. ISTATUS) GOTO 10 


SORT THE RECORDS 


oan 


ISTATUS = SOR#SORT_MERGE( ) 
IF (.NOT. ISTATUS) GOTO 10 


CLEAN UP WORK AREAS AND FILES 


ong 


ISTATUS = SORSEND_SORT() 
IF (.NOT. ISTATUS) GOTO 10 
STOP ‘SORT SUCCESSFUL’ 

10 STOP ‘SORT UNSUCCESSFUL ’ 
END 
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3.8 Sample VAX-11 FORTRAN Program (MERGE) 


Ciriace 
Cree This Program demonstrates the FORTRAN calling sequences 
Cree for the merge RECORD interfaces, 
Crees 
IMPLICIT INTEGER (A-7) 
PARAMETER ORDER=4 ! Order of the merge, 
PARAMETER EOF=2160 ! End of file status code, 
EXTERNAL READ_REC ! Routine to read a record, 
EXTERNAL KOMPAR ! Routine to compare records, 
CHARACTER*80 REC ' A record, 
Gurkha 
Cree First open all the input files, 
Coe 
OPEN (UNIT=10, FILE=’DBB1:X.DAT’ »TYPE=’OLD’ »READONLY, 
* FORM=’FORMATTED? ) 
OPEN (UNIT=11>+ FILE=’DBB1:Y.DAT’ »TYPE=’OLD’ »READONLY , 
* FORM= ‘FORMATTED’ ) 
OPEN (UNIT=12, FILE=’DBB1:2.DAT’ +TYPE=’OLD’ sREADONLY) 
OPEN (UNIT=13, FILE=’DBB1:A.DAT’ »sTYPE=’OLD’ »READONLY ) 
OPEN (UNIT=8+ FILE=‘SYS$OUTPUT:’, TYPE=’NEW’) ! Open the output file, 
Cas 
Cows Initialize the merge, Pass the merge orders the largest 
Core record lengths the compare routine address, and the 
Cree inPut routine address, 
Cex 
ISTAT = SORSINIT_MERGE (ORDER, 0, 80, »KOMPAR »READ_REC) 
IF (.NOT. ISTAT) GOTO 10 ! Check for error, 
Cis 
Cree Now loop getting merged records, SOR$RETURN_REC will 
Coss call READ_REC when it needs input, 
Cases 
ka) ISTAT = SOR$RETURN_REC (REC, LENGTH) 
IF (ISTAT .EQ. EOF) GO TO 30 ! Check for end of file, 
IF (.NOT. ISTAT) GO TO 10 ! Check for error, 
WRITE(8+200) REC ' Output the record, 
200 FORMAT(’ ’,4A) 
GOTO 5 ! And loop back, 
Cees 
Cree Now tell SORT that we are all done, 
| er 
30 ISTAT = SORSEND_SORT() 
IF (.NOT. ISTAT) GOTO 10 ! Check for error, 
CALL EXIT 
Caasa 
Ciaca Here if an error occurred, Write out the error status 
Cause and exit. 
Cia ¥4 
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WRITE(8 +201) ISTAT 
FORMAT(’ ERROR CODE’, 
CALL EXIT 

END 

FUNCTION READ_REC 


120) 


(RECX,» FILE» SIZE) 

This routine reads a record from one of the input files 

for merging. It will be called by SORSINIT_MERGE and by 

SORSRETURN_REC. 

Parameters: 
RECX.wee.ds character buffer to hold the record after 

it is read in, 

FILE. rl.r indicates which file the record is 

to be read from. 1 specifies the 

first files 2 specifies the second 

etc, 


LENGTH.wl.r is the actual number of bytes in 


the record, This is set by READ_REC. 


IMPLICIT INTEGER (A-2) 
PARAMETER EOF=2160 ! 
PARAMETER SUCCESS=1 ! 
PARAMETER MAXFIL=10 ! 


End of file status code, 
Success status code, 
Max number of files, 


LOGICAL#1 FILTAB(MAXFIL) 


CHARACTER*(#) RECX ! Passed length character argument. 


DATA FILTAB/10911912913914515+16517518,19/ ! Table of I/0 unit 


numbers, 
READ_REC = EOF ! Give end of file return 
IF (FILE .LT. 1 .OR. FILE «GT. MAXFIL) RETURN ! If illegal call. 
READ (FILTAB(FILE)» 100, END=50) RECX ! Read the record, 
FORMAT(A) 
READ_REC = SUCCESS ! Return success code, 
SIZE = LEN (RECX) ! Return size of record, 
RETURN 
Here if end of file. 
READ_REC = EOF ! Return "end of file" code, 
RETURN 
END 


FUNCTION KOMPAR (REC1+REC2) 


This routine compares two records. It returns -1 

if the first record is smaller than the second, 

O if the records are equal+ and 1 if the first record 
is larger than the second. 


(continued on next page) 


Calling SORT and MERGE from User Programs 3-33 


PARAMETER KSIZ=20 

IMPLICIT INTEGER (A-2) 

LOGICAL*1 REC1i(KSIZ) »REC2(KSIZ) 3) 
DO 20 T=1sKSIZ 


KOMPAR = REC1(I) - REC2(1) 
IF (KOMPAR .NE. 0) GOTO 50 


20 CONTINUE 
RETURN 

50 KOMPAR = ISIGN (1+ KOMPAR) 
END 
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3.9 Sample VAX-11 MACRO Program (SORT) 


»+TITLE TESTSUB 
+IDENT x91,.01 


THIS IS A SAMPLE MACRO 
PROGRAM WHICH CALLS 
THE SORT SUBROUTINE 
PACKAGE. THERE IS AN 
EXAMPLE USING EACH 


ee ee ee ee we ee ee re ee ee ee 


INTERFACE. 
DATA AREA 

FILENAMEIN: +ASCII /RO1OSQ.DAT/ sINPUT FILENAME 

FILENAMEOUT: +ASCII /TEST.«TMP/ sOUTPUT FILENAME 
»+BLKB 2 

IN_FAB: »BLKB BO 3RMS DATA BLOCKS 

IN_RAB: +BLKB 68 

OUT_FAB: »BLKB 80 

OUT_RAB: »BLKB 68 

FILEIN: »LONG 10 sINPUT FILE NAME DESCRIPTOR 
+ADDRESS FILENAMEIN 

FILEOUT: +LONG 8 sOUTPUT FILE NAME DESCRIPTOR 
»+ADDRESS FILENAMEQUT 

KEYBUF: «WORD 1 sKEY DEFINITION BUFFER 

KEYTYPE: »+WORD 1 

KEYORD: +WORD 0 

KEYPOS: »WORD 1 

KEYSI2: + WORD 10 

INLRL: »+WORD BO sINPUT RECORD LONGEST LENGTH 

WRKFILE: +LONG S00 sWORK FILE SIZE 

NUMWRK : BYTE 4 jNUMBER OF WORK FILES 

TAGSRT: »BYTE 2 3TAG SORT 
»BKLB 2 

KEYAREA: »>BKLB 10 sKEY BUFFER 

RECORDBUF : +BKLB BO sRECORD BUFFER 

RECDESC: +LONG 90 sRECORD DESCRIPTOR 


*ADDRESS KEYAREA 


FIRST THE FILE I/O INTERFACE. DO A TAG SORT ON THE FILE ’RO10SQ,.DAT’ 
INTO THE FILE ‘TEST.TMP’ USING 4 WORK FILES. KEY IS CHARACTER, 10 BYTES 
LONG, STARTING POSITION 1. 


ee ee ee wee ee wes we as 


+EXTRN SORSPASS_FILES »SORSINIT_SORT +-SOR#SORT_MERGE »+SORS$END_SORT + - 
SORS$RELEASE_REC »SOR$RETURN_REC 
+ | 
FILEIO:: 
+ENTRY “MERZ OR3+R4sR5+RGeR7> $s$SAVE REGISTERS 
sDEFAULT ALL OUTPUT OPTIONS 
PUSHAB FILEOQUT +7PUSH FILENAME DESCRIPTOR ADDRESS 
PUSHAB FILEIN 
CALLS #2,SOR$PASS_FILES 3PASS FILENAMES TO SORT 
BLBC RO+s2% sTEST FOR ERROR 
PUSHAB TAGSRT sPUSH SORT TYPE 
PUSHAB NUMWRK 3PUSH NUMBER OF WORK FILES 
CLRO (SP) sDEFAULT LRL AND WORK FILE SIZE 
PUSHAB KEYBUF sPUSH KEY BUFFER ADDRESS 
CALLS #5 ,SORSINIT_SORT sINITIALIZE THE SORT 
BLBC RO1+2$ sTEST FOR ERROR 


LET SORT DO COMPARES 
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CALLS #0 +SOR$SORT_MERGE iSTART SORTING 


BLBC RO+2% sTEST FOR ERROR 
CALLS #0 »,SORSEND_SORT 3D0 CLEAN UP 
BLBC RO +24 


iTEST FOR ERROR 2 


NOW TRY THE RECORD I/0 INTERFACE. RECORDS ARE 80 BYTES LONG, KEY IS 
CHARACTER, 10 BYTES LONG: STARTING IN POSITION i. WORK FILE SIZE IS 


son ee ae wee ee ee we 


500 BLOCKS, 
CALLS #0 ,OPEN_INPUT s;0PEN USER INPUT AND OUTPUT FILE 
BLBC RO+s2% +TEST FOR ERROR 
sDEFAULT SORT TYPE AND WORK FILES 
PUSHAB WRAKF ILE 3PUSH WORK FILE SIZE 
PUSHAB INLRL 3PUSH LRL 
PUSHAB KEYBUF s3PUSH KEY BUFFER ADDRESS 
CALLS #3 ,SORSINIT_SORT sINITIALIZE THE SORT 
BLBC RO+24% sTEST FOR ERROR 
MOVZWL #1000,R6 sSET UP LOOP INDEX 
1%: CALLS #0 +GET_RECORD 3GET RECORD FROM MY FILE 
BLBC RO 2% +sTEST FOR ERROR 
MOYCS3 #10,/RECORDBUF »+KEYAREA 3SET UP KEY IN KEY BUFFER as 
3SORT DOES COMPARES 
PUSHAB RECDESC 3PUSH RECORD DESCRIPTOR 
CALLS #1,SOR$RELEASE_REC sGIVE RECORD TO SORT 
BLBC ROs2$ s5TEST FOR ERROR 
SOBGTR RG+1% 
sSORT DOES COMPARES 
CALLS #0 »,SORSSORT_MERGE 3NO MORE RECORDS TO GIVE 
2%: BLBC RO +6 
3S: 
PUSHAB INLRL s3PUSH RECORD SIZE LOCATION 
PUSHAB RECDESC 3PUSH RECORD DESCRIPTOR Fs 
CALLS #2 ,SORS$RETURN_REC 1GET RECORD BACK 2S) 
CMPL RO»SS#_ENDOFFILE sGOTTEN ALL RECORDS 
BEQL 4 sYES 
BLBC RO»64 sERROR 
CALLS #0 ,PUT_RECORD sPUT RECORD INTO OUTPUT 
BRB 3t 
4¢: CALLS #0 »SORSEND_SORT sFINISH UP 
BLBC RO+»6$% sTEST FOR ERROR 
CALLS #0 ,CLOSE_FILE sCLOSE UP FILES 
MOVL #1,RO sINDICATE SUCCESS 
RET s 
6$: CLRL RO sINDICATE FAILURE ) 
RET 
H 
«END 
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| 3.10 Sample VAX-11 PASCAL Program (SORT) | 


(* Example of a program using SORT. Taken from a FORTRAN example in the SORT 
USER’S GUIDE. : ¥) 


Program sort(output) 3 


label 13, (* error exit *) 
999 § (* Program end *) 


const 


(x#*#* Common sort definitions ****) 


ss#normal= 1 3 
(* Returns from sorg$init_sort, *) 
soré_sort_lon= A*AXLCBOZe § 
sor¢é_miss_kKeyv= AKLcCBOOd 3 
soré_bad_type= *KIcCBOGe 3 
soré_bad_lrl= zKX1cB0OB4 5 
soré_lrl_miss= “X1LCBO7H 35 
soré_bad_file= ’X1cB80Bc 3 
sor$é_work_dev= “ZX1LcB800C 35 
soré$_um_fail= *AKLCBOLG § 
soré_ws_fail= ZX1LcBO2Zd § 
soré_num_kKey= ’AX1L1cB03c 3 
soré_Key_len= ’x1LcB0ac 35 
(* Returns from sor$pass_files, ¥) 
sor$é_var_fix= %’xX1cB064 3 
7 sor$_inconsis= %’xX1cB805c 3 
sor$_orpenin= *xX1¢109c 35 
sor$_oPpenout= “*xLe1dad 3 
(* Returns from sor#release_rec, *) 
soré$_bad_adr= *X1cB094 § 
sor$_extend= AxX1cBOad 5 
soré_omap= *X1cBO9c 3 
sor$_no_wrk= ’X1cBO01d § 
Cc (* Returns from sor#sort_merge, *) 
sor¢é_readerr= AXLc1Obd § 
sor$_writeerr= AxLc1O0dd § 
soré_badfield= AxlclLOl1) 3 
(* Returns from sor$return_rec *) 
ss¢_endoffile= “XB70 5 
(* Returns from sorgend_sort *) 
soré_clean_up= “X1A1cBORA 35 
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(* Key types *) 
character= 13 
binary= 23 
zoned= 363 
Packed_decimal= 43 
dec_lead_overpun= 6 3 
dec_lead_sep= 73 
dec_trail_overpun= 8 3 
dec_trail_sep= 9 3 
float= 10 3 
double_float= 11°63 
g_float= 12 3 
h_float= 13°35 
(* Key orders *) 
ascending= O 4 
descending= 13 
(* Sort types *) 
recordsort= 13 
tagsort= 23 
indexsort= 303 
addresssort= 43 
(¥##* End of general sort definitions ****) 
numberofkeys= 1 3 (* Number of Keys for this sort *) 
type 
byte= O,.255 3 
word= O,,65535 § 
Keybufferblock= packed record 
Keytype: word § 
Keyvorder: word 3 
startPosition: word § 
lengths word 
end 3 
(* The Keyvbuffer., Note that the field ‘buffer’ is a one element array in 
this Program. This shows how a multi-Keved sort would be defined, *) 


Keybuffer= packed record 
mumkKeyss word § 
blocks: Packed arrayCi..numberofkeys] of Keyvbufferblock 
end § 


(* Name types for 


mechanism, 


inPutnametype= 
outPutnametype= 


var 

buffer: Kerbuffer 

status: integer § 
sorttypes byte 35 
numworkfiles: byte 5 


inPutname: 
outPutname: 


3-38 


input and 


inPutnametype 3 
outPutnametyPpe 3 


output files. A necessary fudge for %stdeser 


*) 
Packed array(Ci..10] of char $ 
Packed arrayCi..8] of char 3 

5 (* the actual Kervbuffer *) 

(* return status *) 

(* sort direction (ascending or descending) *) 

(* number of work files *) 

H (* input file name *) 

3 (* output file name *) 


(continued on next page) 


Calling SORT and MERGE from User Programs 





function sor$pass_files( %stdescr innames: inPutnametyPpe 3 
“Astdescr outnames outPutnametyPpe ) : integer $ 


extern § 
Cc function sor¢#init_sort( var buffer: Keybuffer 3 


Aimmed lril:s word $ 
“immed filesize: integer $ 
var numworkfiless: byte 3 
Var sorttypes: byte ) +: integer $ extern $ 


function sorésort_merge : integer 5 extern $§ 


function sortend_sort : integer § extern 3 


begin 


(* initialize data for one 80 byte character Key» starting Position 1» 
3 work files» and a record sort Process *) 


inPutname := ‘’ROLOSQ,DAT’ 35 


outPutname := ‘TEST.TMP’ 3 
with buffer do begin 
numKeys := 193 
with blocksCil] do begin 
Keytype := character 3 
Kevorder := ascending 3$ 
startPosition := 1 § 
length := 80 
end 
7 end § 
numworKkKfiles := 3 3 


© sorttype := recordsort $3 


(* call the sort as a series of functions *) 
(* Pass filenames to sort *) 


status r= sor$pass_files( inpPutnames outPutname ) 3 
if not odd(status) then begin 

(* Process error, Here we just fail *) 

goto 13 
end § 


Cc (* initialize work areas and kervs *) 


status := sor#init_sort( buffers OF OF numworkfiles»s sorttype ) 3 
lf not odd(status) then begin 

(* Process error. Here we Just fail *) 

goto 13 
end 3 


Se a ee ee ee 


(* sort the records *) 





status := sor#sort_merge 3 
if not odd(status) then begin 
(* Process error, Here we just fail *) 


goto 13 
end $ 
(* clean up work areas and files *) 


7 Cc (continued on next page) 
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status := sorfend_sort $ 
if not odd(status) then begin 
(* Process error. Here we just fail ¥*) 


goto 13 2) 
end 34 


writeln( ‘Sort successful.’ ) 3 


goto 999 3 
13: writeln( ‘Sort unsuccessful,’ ) § 
999: 3 
end, 
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3.11 Sample VAX-11 PASCAL Program (MERGE) 


Cc (* This Program merges 3 input files into one output file using the 
record interface, and a user-defined Key comparison routine. *) 
(¥$0-*%) 


Program merge( outrutys infilels infileZ+ infile3+ outfile ) 3 


const 
merge_order = 3 3 (* Number of input files. Must match number of 
infiles declared in ‘program’ statement 
and number of input files opened in Procedure 


‘initfiles’»+ and the case statement in 
function ‘readrecord’, #) 
longest_record_length = 131 35 


ss$_normal = 1 3 
ss$_endoffile = %x870 3 


type 
byte = 0.4.2 


2 3 
C Word = 0,.65535 3 


record_buffer = packed arrayv(l.-longest_record_length] of char $ 
record_buffer_descr = packed record 
length : integer 3 
address : Record_buffer 3 


end 3 
var 
infilel» (* input files *) 
infile2»s 
infile3» 
outfile : text 3 (* output file *) 
rec : record_buffer_descr 35 (* A record descriptor *) 
record_length : word 3 (* Length returned from sor#return_rec *) 
status» (* Function return status code *) 
io: integer 3 (* Loop control variable *) 


function Keycompare( reci» rec2 : record_buffer ) : integer 3 

(* Compare Key field of reci to rec2. Merge is in ascending order on the 
first ‘Keylen’ ascii characters of each record, This routine 
assumes that each record is at least ‘Keylen’ characters long. *) 


const 
Keylen = 3 3 


var 
Keyl» Key2 : packed array(l..Keylen] of char 3 


begin (* Keycompare *) 
for i := 1 to Kevlen do 


begin 
Key1Cil] := recilil 3 
Key2Cil] := rec2Cil 3 
end § 

if Keyl ¢ Key2 then 
Keycompare := -1 

else if Keyl = Kev2 then 
Keycompare := 0 

else 


Keycompare := 1 3 
end 5 (* Keycompare *) 
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function readrecord( var rec record_buffer_descr 3 


filenumber integer § 


var recordsize : word ) : integer 3 e) 


(* Read one record from the specified file ¥*) 


Procedure readone( var filename : text ) $ 


(* read one record from filename. *) 
var 
ch : char $§ 


begin (* readone *) 
recordsize := 0 3 (* initialize record size *) 
if eoln (filename) and not eof (filename) then 
read (filenames ch) $§ 


if eof( filename ) then 


readrecord := ss¢_endoffile (* return eof *) 
else (* read one record *) 
while not eoln( filename ) do 
if recordsize = rec.length then 
begin 


read( filenames ch ) 3 

recordsize := recordsize + 1 $§ 
receaddresslLrecordsize] := ch 3 
end 3 


end 3 (* readone *) 


begin (* readrecord *) J 
readrecord := ss#_normal $$ (* assume no end of file *) 


case filenumber of (* read from specified file *) 

1: readone( infilel ) 

2: readone( infile2 ) 

3: readone( infiled ) 
otherwise 

readrecord := ss#_endoffile (* invalid file number *) 


end § 


end 3 (* readrecord *) 


Procedure initfiles 3 


begin 
(* open input files: sequential access» variable length records,s 
RMS CR carriage control *) 
open( infilel»s ‘’INFILE1.DAT’» old ) 3 
open( infile2»s ‘’INFILE2.DAT’» old ) 3 
open( infile3» ‘INFILE3.DAT’» old ) 3 


(* open output file: same attributes as input files» except that 
it is anew file *) 
open( outfiles ‘OUTFILE.DAT’ ) 3 


(* ready input files for reading *) 
reset( infilel 

reset( infile2 ) 
reset( infile3 ) 


we we we 
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(* ready output file for writing *) 
rewrite( outfile ) 3 


end 3 (* initfiles *) 


(* Merge function declarations. All Parameters 
are passed using by-reference semantics. *) 


function sor#init_merge( merge_order =: byte 3§ (* number of files 
to merge *) 
“immed Keybuffer integer 3 (* not used *) 
longest_record_length word § 
“immed merge_options integer 


: (* not used *) 
“immed function kKeycompare : integer 
e 


en ee 


“immed function readrecord integer 
) : integer $§ xtern § 


function sorsreturn_rec( var rec : record_buffer_descr 3 


var record(size word ) : integer §$ extern $§ 


function sortéend_sort : integer 3 extern 3 


Procedure error( status : integer ) $§ 
(* write error message and exit thru systexit *) 


Procedure sys#exit( status : integer ) § extern 3 


begin (* error *) 
writeln( ‘Merge unsuccessful, Status= hex ‘+ status:8 hex ) 3 
sys#exit( status ) $§ 

end 5 (* error *) 


begin (* merge *) 
initfiles 3 (* open and ready all files *) 


(* Initialize the merge. Pass the merge orders the Key comparison 
routine address» the input routine address» and the longest 
record length *) 

Status := sorsinit_merge( merge_orders Oy longest_record_length~» 

O,s Keycompares readrecord ) § 

if not odd( status ) then 

error( status ) 3$ 


(* Loop getting merged records. SOR#RETURN_REC will call READRECORD 
when it needs input *) 


new( rec.,address ) $ (* get a record buffer *) 
rec,length := longest_record_length 3 (* save buffer length *) 


repeat 
status := sor$return_rec( rec» record_length ) 3§ 
if odd( status ) then (* Success» write record to output file *) 
begin 
for i := 1 to record_length do 
write( outfile,s receaddressCil] ) 3§ 
writeln (outfile) $§ 


end 5 (continued on next page) 
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until not odd( status ) 3 
if status “<> ss¢_endoffile then 


error( status ) § oe) 


status i= sorfend_sort 3§ 
if not odd( status ) then 
error( status ) 3 
Writeln( ‘Merge successful.’ ) § 


end, (* merge #) 
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3.12 Sample VAX-11 PL/I Program (SORT) 


/* 
This program calls the SORT routines to perform an alphabetic 
sort on a file, 

*/ 

SORTEM: PROCEDURE RETURNS (FIXED) $ 


/* 


Include the declarations of the SORT procedures required 
for a sort using the file interface, 

*/ 

*ZINCLUDE SOR#PASS_FILES3; 

“ZINCLUDE SORSINIT_SORT3 

%ZINCLUDE SORSSORT_MERGE 3 

“ZINCLUDE SOR#SEND_SORT; 

“ZINCLUDE $STSDEF 5 


/* 
Declare the input and output files3 these are logical names 
that must be defined before the program is run, 
*/ 
DECLARE INPUT_FILE CHARACTER(G) STATIC INIT(‘INFILE’), 
OUTPUT_FILE CHARACTER(7) STATIC INIT(‘OQUTFILE‘)3 


/* 
Declare the Key buffer array required to sort the first 80 
characters of any record. This ‘array’ is declared as a 
structure to clarify the example. An array can also be used, 

*/ 

DECLARE 1 KEY_BUFFER STATIC, 

NUMBER_OF_KEYS FIXED BINARY (15) INIT(1), 

KEY_TYPE FIXED BINARY (15) INIT(1)+ /* character ¥*/ 

KEY_ORDER FIXED BINARY (15) INIT(O)»s /# ascending order */ 

START_POS FIXED BINARY(15) INIT(1)>+ 

2 KEY_LENGTH FIXED BINARY(15) INIT(80), 

LONGEST_RECORD FIXED BINARY(15) STATIC INIT(80)3 


J PI PI PI Po 


/* 


Declare global symbol names for RMS values to define the output file 
*/ 


DECLARE (FAB$C_VAR» FAB$C_REL) GLOBALREF FIXED BINARY(31) VALUE} 


DECLARE RECORD_TYPE FIXED BIN(7) + 
FILE_ORG FIXED BINARY(7)3 


RECORD_TYPE = FABSC_VAR3 
FILE_ORG = FABS$C_REL$ 


/* 
Call the SORT routines in the reauired order, 


After each call to SORT» check STS#SUCCESS. 
*/ 


STS$VALUE = SORSPASS_FILES( INPUT_FILE »OUTPUT_FILE» 


FILE_ORG+RECORD_TYPE) $ 
IF “STS$SUCCESS THEN GOTO ERROR; 


STS$VALUE = SORSINIT_SORT(KEY_BUFFER +LONGEST_RECORD) 3 
IF “STS$SUCCESS THEN GOTO ERROR; 


STS$VALUE = SOR$SORT_MERGE()3 
IF “STS$SUCCESS THEN GOTO ERROR 


STS$VALUE = SORSEND_SORT() 3 
IF *“STS$SUCCESS THEN GOTO ERROR} 
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/* successful completion ¥*/ 


RETURN(1)3 


/1* 
All errors return here with the value of STS$VALUE. 2) 


*/ 
ERROR: 
PUT SKIP(2) EDIT (‘SORT failed. 
(Ark sF(B))5 


RETURN(STS$VALUE) 5 


Error code’ +STS$VALUE) 


END$ 
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3.13 Sample VAX-11 PL/I Program (SORT) 


/* 
This Program sorts the file STATE_FILE based on the field 
CAPITAL.NAME in each record, 


Logical name equivalences are reaguired for the input file STATE_FILE 
and an output file SORTED_FILE. 

*/ 

statesort: Procedure options (main) returns (fixed binary(31))3 


/* 

Declare SORT routines 
*/ 
“ZINCLUDE SOR#SINIT_SORTS$ 
%ZINCLUDE SOR#SORT_MERGES 
ZINCLUDE SORSEND_SORT 3 
ZINCLUDE SOR#RELEASE_REC3 
ZINCLUDE SORSRETURN_REC3 


ZINCLUDE $STSDEF 3 


DECLARE SS#$_ENDOFFILE GLOBALREF FIXED BINARY(31) VALUE» 
EOF BIT(1)35 


EOF = ‘0’B$ 
/* 
Key buffer and data for SORT routines 
*/ 
DECLARE 1 KEY_BUFFER STATIC, 


NUMBER_OF_KEYS FIXED BINARY (15) INIT(1)>, 
KEYTYPE FIXED BINARY (15) INIT(1)+» /* character Keys */ 
KEY_ORDER FIXED BINARY (15) INIT(O)» /* ascending order */ 
START_POS FIXED BINARY(15) INIT(25)» 
KEY LENGTH FIXED BINARY(15) INIT(20) 5 
LONGEST. RECORD FIXED BINARY(15) STATIC INIT(19G6)» 
KEYFIELD FIXED BINARY(7) + /* Code to decide sort */ 
RETURN_LENGTH FIXED BINARY(15)5 /* Required Parameter */ 
/* Declare a buffer to construct each record to be passed to SORT */ 


PI PI PI PI PI 


DECLARE 1 STATE_RECORD; /* complete record */ 
2 KEYFIELD CHARACTER(20) , 
2 STATE+ 


3 NAME CHARACTER (20) 4 
3 POPULATION FIXED BINARY(31); 
3 CAPITAL» 

4 NAME CHARACTER (20) » 

4 POPULATION FIXED BINARY(31)>+ 
3 LARGEST_CITIES(2), 

4 NAME CHARACTER(30) » 

4 POPULATION FIXED BINARY(31) +, 
3 SYMBOLS; 

4 FLOWER CHARACTER (30), 

4 BIRD CHARACTER (30)3 


DECLARE 1 RECORD_DESCRIPTOR, 
2 LENGTH FIXED BINARY(15), 
2 FILLER FIXED BINARY(15), 
2 ADDRESS POINTER: 


(continued on next page) 
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/* 
Input and output files 
*/ 
DECLARE STATE_FILE FILE INPUT RECORD SEQUENTIAL, 
SORTED_FILE FILE RECORD OUTPUT SEQUENTIAL; 


/* 
call SORSINIT_SORT 
*/ 
STS$VALUE = SOR#INIT_SORT(KEY_BUFFER»LONGEST_RECORD) 3 
IF “STS#SUCCESS THEN RETURN(STS#VALUE) 3 
/* 


Enter DO-loorp to read the input file STATE_FILE. Then» call 
So-$KELEASE_REC. The record consists of the Key field concatenated 
th the contents of STATE. 
*/ 
OPEN FILE(STATE_FILE) § 
RECORD_DESCRIPTOR.LENGTH = 1963 
RECORD_DESCRIPTOR.ADDRESS = ADDR(STATE_RECORD) 3 
ON ENDFILE(STATE_FILE) EOF = ‘1’B3 
READ FILE (STATE_FILE) INTO(STATE)3 
DO WHILE (*EOF)3 
STATE_RECORD.KEYFIELD = CAPITAL.NAME3 
STS$VALUE = SOR#RELEASE_REC ( 
RECORD_DESCRIPTOR) 3 
IF “STS#SUCCESS THEN RETURN(STS$VALUE) $ 
READ FILE(STATE_FILE) INTO(STATE)$ 
END$ 
CLOSE FILE(STATE_FILE)3 
PUT SKIP LIST(‘**** ALL RECORDS RELEASED’) 3 


/* 
Call SOR$SORT_MERGE to sort the records that were released 
*/ 
STS$VALUE = SORS$SORT_MERGE() 3 
IF “STS#SUCCESS THEN RETURN(STS$VALUE) 3 
/* 


Loop through the DO-group to get back each record and write it 
to the sorted output file, 
* F 
STS$VALUE = 13 
OPEN FILE(SORTED_FILE) OUTPUT; 
RECORD_DESCRIPTOR.LENGTH = 1763 
RECORD_DESCRIPTOR.ADDRESS = ADDR(STATE)3 
DO WHILE (STS$¥ALUE “= SS$_ENDOFFILE) $ 
STS$VALUE = SOR#SRETURN_REC(RECORD_DESCRIPTOR »RETURN_LENGTH) 3 
IF STS$SUCCESS THEN WRITE FILE(SORTED_FILE) FROM (STATE); 
ELSE IF *“STS$SUCCESS & (STS$VALUE *= SS$_ENDOFFILE) 
THEN RETURN(STS$VALUE) § 
END$ 
CLOSE FILE (SORTED_FILE)3$ 
/* 
Call SOR#END_SORT to finish up 
*/ 
STS$VALUE = SORSEND_SORT()3 
IF “STS#SUCCESS THEN RETURN(STS$VALUE) $ 
RETURN(1)$ /* successful completion #*/ 
/+* 
All errors come here to return to the command level with the 
status value of the error in RO, 
*/ 
ERROR: RETURN(STS$VALUE) $ 
END$ 
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Chapter 4 
Improving SORT Efficiency 


c 


This chapter provides a brief description of how SORT operates internally, 
explains the meaning and use of SORT statistics, and suggests procedures 
the user and system manager can follow to make a sorting operation more 
efficient. 


Cc 4.1 How SORT Operates 


The following description of SORT’s internal operation does not try to give 
all the details of the process. Instead, it gives a summary of what happens 
during a sorting operation, paying special attention to the sort tree and 
work files because these can be modified by the user for greater SORT 
efficiency. 


SORT takes two forms: (1) a control program called the utility that the user 
© invokes with a command line and (2) a package of subroutines the user can 
call from a program. During a utility sort the control program calls the 
subroutines as part of its processing. Although there are some differences 
in operation between the two forms, both go through the main phases 

described below. 


4.1.1 Initialization Phase 


SORT first reads and interprets the command line, specification file, or 

SOR$INIT__SORT parameters and stores the parameters and qualifier val- 

ues. Any errors in this information are reported at this point. If there are 

no errors, SORT opens the input file and creates the output file. (Record 

interface does not use this step.) Next, SORT initializes key comparison 

information, generates the key comparison routine, and allocates the space 
Cc needed for input and output buffers and the sort tree. 
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4.1.2 Sort Phase 


After the initialization phase is complete, SORT begins reading records and 
placing them into a “sort tree” in the working set in memory. (For tag, 
address, or index sort only the key is placed in the sort tree.) This process 
continues until the sort tree is full or all records have been read. If all 
records fit into the sort tree, they are sorted in memory, and no work files 
are created. 


If the working set becomes full, SORT begins to move records to a work file, 
where it builds sorted strings. The first record it removes from the sort tree 
is one with the smallest key. 


SORT then reads the next input record into the sort tree. If there are more 
records to be read, it moves a second record from the sort tree to the string 
in the work file. This time it again selects a record with the smallest key, 
but not a key smaller than that of the record just moved. Moving a record 
with an equal or larger key creates a sorted string in the work file. 


This process repeats until (1) all records have been read, or (2) SORT can- 
not transfer a record with an equal or higher key to the string. In the latter 
case, SORT begins building a second string, again selecting first a record 
with the smallest key from those in the sort tree. 


When all records have been read into the sort tree, they are moved one by 
one in sorted order to the string being built in the work file. If at some point 
no record remaining in the sort tree has an equal or higher key than the 
record most recently moved into the work file, SORT begins a new string. 


After all records have moved from the sort tree to the work file, the work 
file contains any number of strings, each of which is a set of sorted records 
(or keys, for other than record sort). 


4.1.3 Merge Phase 


In the internal merge phase SORT begins merging the sorted strings in the 
work file. Up to ten strings are merged into one ordered string. If the work 
file contains no more than ten strings, the records in the merged string are 
written to the output file or returned to the calling program. (In tag sort, a 
subroutine uses the merged string of keys to read the records in the sorted 
sequence before it writes them. In address sort the output file contains 
RFAs only; in index sort, it contains keys and RFAs.) , 


If the work file contains more than ten strings, the merged string is written 
to the second work file. Then another merge of up to ten strings takes place, 
and this merged string is also written to the second work file. 


This internal merging continues until all sorted strings in the first work 
file have been merged and moved to the second work file. This process is 
one merge pass. 
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If the strings have been moved to work file #2, another merge pass begins, 
this time moving merged strings from work file #2 to work file #1. Again, 
if work file #2 contains no more than ten strings, the merged records are 
written directly to the output file or returned to the calling program. 


The merging process continues until all records have been merged into one 
ordered string, which is the final sorted file. 


4.1.4 Clean-Up Phase 


After the last record is written, SORT closes the input and output files (for 
utility sort and file interface), closes and deletes the work files, and releases 
memory. Finally, for interactive or batch sorting operations, the utility gets 
the SORT statistics and prints or displays them, then returns to the 
VAX/VMS command interpreter. 


4.2 Understanding and Using SORT Statistics 


The /STATISTICS qualifier causes SORT to display statistics like those in 
the following example. You can use the SORT statistics to judge the effi- 
ciency of a sorting operation and determine the adjustments needed to 
improve performance. 


Records read: 793 Longest record lengths: 73 
Records sorted: 793 Input multi block counts: 16 
Records output: 793 Suteut multi block count: 16 
Maximum working set used: 200 Input multi buffer count: 2 
Yirtual memory added: 717312 Output multi buffer count: 2 
Direct I/O count: 10 Number of initial runs: 2 
Buffered I/O count: 13 Order of the merge: 2 
Page faults: 713 Number of merge passes: 1 
Elapsed time: 00:00:06,951 CPU time: 331 


If the number of records read, sorted, and output is not the same, this 
discrepancy indicates a problem with I/O or with the records themselves. 
The difference can be caused by input or output errors, null records in the 
file, or records containing invalid data in key fields. If fewer than ten 
records contain invalid data, SORT continues; if ten or more do, SORT stops 
executing. 


Maximum working set used shows the size in blocks of the working set 
used for the sort. Adjusting this value is one of the ways to improve SORT 
efficiency; for medium and large files, the higher it is, the better. 


The multi block and buffer counts indicate the amount of I/O optimiza- 
tion. Depending on the size of the working set, SORT creates for input and 
for output one or two buffers each. A buffer can hold from 1 to 16 blocks. 
Having two buffers permits overlap of reading and processing and thus 
speeds up the sort. The more blocks each buffer holds, the less time is spent 
in I/O. The closer these numbers are to the maximums of 2 and 16, the 
greater the optimization. If all counts are 1, no optimization took place. 
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The total of the two I/O counts is the number of I/O movements needed to 
get and write data. The lower these are, the more efficient the sort was. 
This count decreases as the multi block and buffer counts increase. 


The order of the merge is the number of sorted strings that are merged in 
the final merge pass. 


Initial runs are the sorted strings created in the work file. If all records 
were sorted in memory, this number is 0. 


The number of merge passes is the number of times SORT must pass 
through a work file, merging the strings, until one sorted string results. 
The number of initial runs and the number of merge passes shows you how 
close the data is to fitting in memory. The higher these numbers are, par- 
ticularly the number of passes, the longer SORT takes and the further 
away the working set size is from containing the data. 


The number of page faults also indicates how well the data fit into mem- 
ory. The higher the number of page faults, the less efficient the sort is. 


Longest record length value is obtained from RMS unless the user sup- 
plies it. You can use it to check the RMS value. 


Elapsed time is the total wall clock time in hours, minutes, seconds, and 
1/100 seconds from the start to the end of the sort run. CPU time is the 
time in 1/100 seconds that the processor spends handling the data; it does 
not include I/O time or time waiting for another process to execute. The 
closer CPU time is to elapsed time, the better optimization you are seeing 
in I/O. 


Virtual memory added is the number of bytes of virtual memory SORT 
used for the data. 


4.3 What the User Can Do 


44 


Any software sorting routine can be written to work most efficiently in the 
environment in which it is likely to be used most frequently. Environment 
variables include such things as type of I/O devices, key data type, file size, 
and relative size of key and record. VAX—11 SORT/MERGE is designed for 
an environment of random access disk devices, fairly large files, and 
medium size records and keys. 


SORT software automatically provides the most efficient sort for the data 
type(s) of your key(s). For each sort, it generates a key comparison routine 
tailored to the particular keys being sorted. 


Two ways the user can improve SORT efficiency are by: (1) adjusting work- 
ing set size and (2) placing work files effectively. 


4.3.1 Working Set Quota 


For SORT to work efficiently, it is important to use the largest working set 
possible. Normally, this means setting a working set limit to your author- 
ized working set quota. For very small files, however, a smaller working set 
quota may be more efficient. 
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During the sort phase, records are read into the sort tree in memory (that 
is, the working set) until it is full. If the space in the working set cannot 
hold all the records, SORT transfers sorted strings to a work file on a 
temporary storage device. SORT must then take the time to perform merge 
passes until one sorted string results. If all records can be sorted in main 
memory, SORT does not need to perform any merge passes. 


A larger working set also increases sort efficiency when the sort uses work 
files, as in most sorts of large files. SORT uses the larger working set space 
to create a larger sort tree. The larger the sort tree, the greater chance 
SORT has of creating longer and fewer sorted strings in the work file. 
Fewer strings means fewer merge passes and a faster sort. 


4.3.2 Location of Work Files 


Another important consideration is the location of the work files. Normally 
SORT places work files on your default device, but you can select a differ- 
ent device for any work file by specifying: 


ASSIGN (device): SORTWORKn 


The n represents the number of the work file (0 to 9). 


You can increase SORT efficiency by placing work files on: 


e The fastest device(s) available 
© Device(s) having the least activity 
e The least full device(s) available 


e Separate devices 


Placing work files on separate devices permits overlap of the read/write . 
cycle. You can gain more speed by placing the input file and output file, as 
well as each work file, on different devices. The ideal configuration for 
SORT is to have the input and output file and each work file all on separate 
empty disks being used only by SORT during the sorting process. However, 
this is seldom possible, so the next best procedure is to place work files on 
devices meeting as many of these requirements as possible. 


Usually there is no advantage to using more than two work files. However, 
if the available disks are too small or too full for SORT work files, increas- 
ing the number of work files makes each work file smaller so that it can fit 
onto a small or nearly full disk. 


Because SORT does not create work files until it needs them, you do not 
gain in speed by specifying 0 work files to keep work space in real memory. 
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4.3.3 Process 


Although typically you select a sort process for reasons other than effi- 
ciency, you should understand the differences in speed among the four sort 
processes. See Section 2.1.2 for a description of these differences. In any 
operation in which the sorted records will be retrieved in order, record sort 
is usually the fastest sort process. 


If limited work space is a problem, consider using tag sort, which requires 
less space than record sort. 


4.4 What the System Manager Can Do 
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The system manager can designate one batch queue for sorting jobs and 
give this queue a very large working set quota. He can also adjust parame- 
ter values for greatest SORT efficiency. 


The system manager can determine the following SORT performance 
parameter values based on the overall system usage: number of users, 
sort process most commonly run, and the amount of real memory available. 


¢ System per process working set quota (WSMAX) 

¢ System per process virtual page count (VIRTUALPAGECNT) 

¢ System per process section count (PROCSECTCNT) 

¢ System modified page writer cluster factor ( MPW__WRTCLUSTER) 


The values recommended are based solely on SORT considerations; it is up 
to the system manager to integrate other system considerations with these 
in determining the final values. 


4.4.1 Working Set Quota 


The maximum for this value should be set to the largest size any sort job 
would ever need. For very large files, working sets of 500 to 1000 pages are 
not at all unreasonable, provided the system has enough physical memory 
to handle them. To prevent users from monopolizing real memory, the sys- 
tem manager can set individual maximums on a per user basis through the 
authorization file. The general rule is: the smaller the working set, the 
slower the sort. 


4.4.2 Virtual Page Count 


For this parameter the current value as well as the maximum value should 
be set to a minimum of 7 times the value of the working set quota maxi- 
mum. When SORT begins executing it requests at least 7 times the work- 
ing set quota of virtual memory from the system. If this parameter is too 
low, SORT may be unable to run. 
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4.4.3 Process Section Count 


This parameter needs a value of 20 to guarantee that SORT will not fail. If 
the parameter is set too low, SORT cannot run in larger working sets be- 
cause of internal mapping failures. SORT itself never needs a value higher 
than 20, but if a program that uses many process sections also calls SORT 
subroutines, more than 20 process sections may be required. 


4.4.4 Modified Page Writer Cluster Factor 


The value of this parameter never causes SORT to fail, but it can affect 
performance greatly. For any larger sorts (that is, using working sets of 250 
pages or greater) the larger this parameter, the better. Values of 64 and up 
are not too large. Be sure to adjust MPW__HILIM and MPW__LOLIMIT 
accordingly. For more information refer to the SYSGEN procedures in the 
VAX-11 Software Installation Guide. 
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Appendix A 
Error Conditions 


You can encounter error conditions at three operating levels: with the 
VAX/VMS DCL command interpreter, with SORT/MERGE, and with 
VAX-~11 RMS. 


There are three categories of error conditions: 


e Errors caused by I/O or other system failures 


e Errors caused by misinformation passed to SORT as a parameter of a 
subroutine call 


e Errors caused by invalid data in a key field 


For the SORT/MERGE utility, all errors are signaled to the system; this . 
signal causes a message to be displayed or printed. For the subroutines, an 
error status value is returned to the calling program. 


SORT handles both fatal and warning errors. Fatal errors (severity level F) 
cause SORT to halt processing; warning errors (severity level W) cause a 
warning message to be displayed and allow sort processing to proceed. 


Only invalid data errors and a few RMS errors cause warning error 
messages. System or I/O failures and bad subroutine parameters are fatal 
errors. For additional information regarding error condition handling, refer 
to the VAX/VMS System Services Reference Manual. 


A.1 Command Interpreter Error Messages 


In interactive mode, when you enter a command line incorrectly, the com- 
mand interpreter issues a descriptive error message telling you what was 
wrong. For example, if you specify more than one parameter for a command 
that accepts a single parameter, you receive the message: 


%ZDCL-W-MAXPARAM, maximum Parameter count exceeded 


You must then retype the command line. 


Other error messages may occur during execution of a command. These 
messages can indicate such errors as a nonexistent file or a conflict in 
qualifiers. Not all messages from the system indicate errors; other mes- 
sages are informative or warn you of a particular condition. 


The VAX/VMS system messages have the general format: 


%XXX-L-CODE, text 


Descriptive comment 
Shorthand code for the message text 
Severity level: 

S= Success 

I=Information 

W = Warning 

E=Error 

F = Fatal 
Mnemonic for the operating system 
program issuing the message 


Example: 


“SORT-W-CLOSEOUT:s error closing output (output file-specification) 


Because these messages are descriptive, you should be able to understand 
what you need to do differently when you issue the command again. But, if 
you do not, the VAX/VMS System Messages and Recovery Procedures 
Manual lists all the possible command interpreter error messages and de- 
scribes what you can do to correct a command interpreter error. 


A.2 SORT/MERGE Error Messages 
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The following VAX-11 SORT/MERGE error messages are listed in 
alphabetical order. They all have the same format as command interpreter 
messages, that is: 


%SORT-(severity level)—(code),(text). 


The error message descriptions observe the following conventions: 


¢ Only the (code), (text) part of the message is shown in the following list. 


e (filespec) indicates a file specification. 
For example: DB1:[153,10]TEST.TMP;3. 


© (number) indicates the user entered numeric value. 


e LRL means the longest record length (specified in bytes). 


Error Conditions 


BAD_ADRs invalid descriptor address specified, 


You passed the subroutine package an address for a descriptor, and the 
descriptor was invalid format. Character string descriptors in VAX con- 
sist of two longwords. The first word of the first longword contains the 
character string length in bytes. The second longword contains the 
address of the string. 


User Action: Check character string format. 


BADFIELD,» (filespecys or field text that is invalid) field in- 
valid at (number), 


Bad data in key field or command. In this message, (number) indicates 
the record number of the record containing bad data in hex. 


User Action: Check key field data type and the starting positions and 
lengths (see Section 2.1.2). 


BAD_FILE» file size invalid, 


You specified a negative file size or a zero file size. File size must be 
greater than zero. 


User Action: Specify a file size greater than zero. 


BAD_KEY» invalid Key specification. 


Either the key field size, position, data type, or order is incorrect within 
the key definition. Positions start at one and cannot be greater than the 
maximum record size. Size must be less than or equal to 255 for charac- 
ter data, 1, 2, 4, or 8 (byte, word, longword, or quadword) for binary 
data, and less than or equal to 31 for decimal. ™ 


User Action: See Section 2.1.2 and check the command string key 
specifications. 


BAD_LEN» output record length less than 18 bytes for magtape,. 


Magnetic tape requires record lengths to be at least 18 bytes. 


User Action: Check your output file record length. 


BAD_LRL»+ input file (filesPrec),. 
Record size greater than specified LRL. 


In reading the input file, SORT encountered a record longer than the 
specified LRL. The record will be truncated to the LRL and sorted. 


User Action: Re-execute SORT with a larger LRL. 
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BAD_MERGE?+ merge order must be between 2 and 10, 
You specified fewer than 2 or more than 10 input files to MERGE. 


User Action: Specify between 2 and 10 input files. 

BAD_ORDER» input file (number) is out of order, 
A MERGE input file is not in order on the specified key. In this message 
(number) refers to the number of the input file in the list of input files. 
You must specify / CHECK__SEQUENCE to receive this message. 
User Action: Sort the specified file and re-submit to MERGE. 


BAD_ROUTIN» bad routine address has been Passed, 
You passed the subroutine package an incorrect address for a routine. 


User Action: See Chapter 3 and specify the correct routine address. 


BAD_SPEC;+ invalid specification file record, 
FIELD: (record specification), 


An incorrect field was specified in the specification file record. (record 
specification) indicates bad record contents. 


User Action: See Section 2.4 for descriptions of specification file record 
formats and change field specifications. 


BAD_TYPE+ invalid sort Process, 


You passed the subroutine package a sort type code of less than 1 or 
greater than 4 if file I/O or not equal to 1 if record I/ O, or an invalid 
key word in command /PROCESS. Legal values are 1-4 for file I/O, 
and RECORD, TAG, INDEX, or ADDRESS for command /PROCESS 
parameter. 


User Action: Specify a different sorting process. 

CLEAN_UP; failed to reinitialize work area and files, 
SORT was unable to deallocate the extra virtual memory, deassign 
work file channels, or readjust working set size. For the SORT utility, 
this is a warning of little importance. For the SORT subroutine pack- 
ages, this could mean a failure to be able to recall SORT from the same 


program until it has exited. This is an internal error. 


User Action: Exit from the user program before re-executing SORT. 


A-4 Error Conditions 


CLOSEIN» error closing (filespec) as inPut. 


An error occurred closing an input file. This message is usually accom- 
panied by an RMS message indicating the reason for the failure. 


User Action: Take corrective action based on the associated message. 


CLOSEOUT,» error closing (filesrPec) as output. 


An error occurred closing an output file. This message is usually accom- 
panied by an RMS message indicating the reason for the failure. 


User Action: Take corrective action based on the accompanying 
message. 


EXTEND» failed to extend work file, 


SORT failed to extend a user’s temporary work file. Either the device is 
full, or the user does not have extend privilege. 


User Action: See Section 4.3.2 and reassign work files to a different 
device with more space, and make sure you have extend privilege on 
that directory. 


INCONSIS» inconsistent data in file (filespec),. 


If you specified /OVERLAY plus other output file qualifiers, SORT will 
verify that the information in the existing file matches the information 
you provided. If it does not, this error message is reported. Unless you 
specifically want a verification, /OVERLAY should be used without 
other qualifiers. 


User Action: Check the command string output file qualifiers (see 
Section 2.1.3). 


IND_OVR» indexed sequential output reauires overlay qualifier, 


You specified indexed output file organization without specifying © 
/OVERLAY. 


User Action: You must create the indexed file first with a utility such as 
the RMS DEFINE utility. The primary key of the file should be the 
same as the sort key for efficiency but is not required to be. Then you 
must specify /OVERLAY in the SORT command string. 


INP_FILES» too many input files, 


You listed more than 10 input files. 


User Action: Reduce the number of input files or combine them so that 
you list no more than ten. 
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KEY_LEN+ Key length invalid» key number (number), size (number), 


The key size is incorrect for the data type, or the total key size is greater 
than 255 (or 251 if you are using /STABLE). 


User Action: See Section 2.1.2 and specify correct key field size. Size 
must be less than or equal to 255 for character data, 1, 2, or 4 for binary 


data, and less than or equal to 31 for decimal. Also, only ascending or 
descending order is allowed. 


LRL_MISS» LRL must be specified, 


If record I/O interface subroutine package is selected, the longest record 
length (LRL) must be passed to SORT or MERGE in the call. 


User Action: Specify LRL. 


MAP, failed to map work file, 
This is an internal SORT failure. 
User Action: Verify that the system parameter “maximum process 


sections” has been set up at 20. If it has, then report this failure to a 
specialist. Otherwise, set that system parameter to 20. 


MISS_KEY+s Key specification missing, 


SORT did not find any key definition in either the command line or 
specification file, or in the parameters to the subroutine package. 


User Action: You must input at least one key definition in one of these 
three areas. 


NO_WRK» need work files cannot do SORT in memory. 


You specified /WORK__FILES=0 indicating the data would fit in 
memory, but the data was too large. 


User Action: Either increase the working set quota, or allow SORT to 
use two or more work files. 


NUM_KEY» too many Keys specified, 


Up to ten key definitions are allowed. Either too many have been speci- 
fied, or the NUMBER value is wrong. 


User Action: See Section 2.1.2 and check your command string key field 
specifications. 


Error Conditions 


OPENIN» error opening (filespec) as inPute 


An input file cannot be opened. This message is usually accompanied by 
an RMS message indicating the reason for the failure. 


User Action: Take corrective action based on the associated message. 


OPENOUT>» error opening (filespec) as outPut,. 


An output file cannot be opened. This message is usually accompanied 
by an RMS message indicating the reason for failure. 


User Action: Take corrective action based on the associated message. 


READERR» error reading (filesPec),. 


An input file record specified cannot be read. This message is usually 
accompanied by an RMS message indicating the reason for the failure. 


User Action: Take corrective action based on the associated message. 


SORT_ON» sort already in Progress, 


You tried to call the SORT subroutine package with calls in the wrong 
order, or to recall it before it finished running the previous sort. 


User Action: Reorder the subroutine calls and then re-execute SORT. 


TOO_BIG» record size larger than declared maximum, 


A record is larger than the LRL you specified. 
User Action: Change LRL value. 


VYAR_FIX» cannot change variable length records into fixed 
length. 


You specified variable length input records and requested fixed length 
output. 


User Action: Output records must be variable or controlled in this case. 


UM_FAIL» failed to get reauired virtual memory (number), 


SORT could not get the amount of virtual memory required for the sort. 
(number) indicates the number of bytes needed. 


User Action: If the SORT utility is being run, decrease the working set 
quota; if either SORT subroutine package is being run, either decrease 
the quota or return some memory to the system inside the user’s pro- 
gram before calling SORT. 
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WORK_DEY>s work file (filesrpec) device sPecified not random 
access or mot local, 


Work files must be specified for random access devices that are local to 
the CPU the sort is being performed on (that is, not on node in a net- 
work). Random access devices are disk devices. 


User Action: Specify the correct device. 
WRITEERR» error writing (filespec), 


An output file record cannot be written. This message is usually accom- 
panied by an RMS message indicating the reason for the failure. 


User Action: Take corrective action based on the associated message. 


WS_FAIL»s failed to get required working set space (number), 


SORT could not get the required amount of real memory space. A mini- 
mum 75 page working set is needed. (number) indicates number of 
pages available. 


User Action: Increase the working set quota. 


A.3 VAX-—11 RMS Error Codes 
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If an error occurs in an input or output operation, an RMS code is returned 
to your program by the operating system. Often RMS messages are linked 
with SORT/MERGE messages. 


All VAX-11 RMS error messages have the same format as command inter- 
preter messages, that is: 


%RMS~(severity level)—(code),(text). 


Like the command interpreter error messages, RMS error messages are 
descriptive. The descriptions should make clear what you need to do differ- 
ently. Refer to the VAX—11 Record Management Services Reference Manual 
for a list of RMS error codes and recovery procedures. 


Error Conditions 
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Octal /Hexadecimal /Decimal Conversion 


B.1 Octal /Decimal Conversion 


To convert a number from octal to decimal, locate in each column of the 
table the decimal equivalent for the octal digit in that position. Add the 
decimal equivalents to obtain the decimal number. 


To convert a decimal number to octal: 


1. Locate the largest decimal value in the table that will fit into the deci- 
mal number to be converted 


2. Note its octal equivalent and column position 


3. Find the decimal remainder 


Repeat the process on each remainder. When the remainder is 0, all digits 
will have been generated. 


32,768 
65,536 
98,304 
31,072 
163,840 
169,608 
229,376 


NY nan fF WOW NH KF OS 


0 
1 
2 
3 
4 
5 
6 
7 





B.2 Powers of 2 and 16 


Powers of 2 


2°*n 


256 

512 
1024 
2048 
4096 
8192 
16384 
32768 
65536 
131072 
262144 
524288 
1048576 
2094304 
4194304 
8388608 
16777216 


n 


Powers of 16 


16**n 


1 

16 

256 

4096 

65536 

1048576 

16777216 
268435456 
4294967296 
68719476736 
1099511627776 
17592186044416 
281474976710656 
4503599627370496 
72057594037927936 
1152921504606846976 


WOANDURWNr OO FS 


B.3 Hexadecimal to Decimal Conversion 


For each integer position of the hexadecimal value, locate the correspond- 
ing column integer and record its decimal equivalent in the conversion 
table A.5. Add the decimal equivalent to obtain the decimal value. 


Example: 
DOSOOADO (16) = ?(10) 
pooo0000 = 3,489,660,928 
500000 = 5 +242 ,880 
Ao0o = 2+560 
DO = 208 
DOSOOADO = 3,/494,904,576 


B.4 Decimal to Hexadecimal Conversion 


1. 
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Locate in the conversion table A.5 the largest decimal value that does 
not exceed the decimal number to be converted. 


Record the hexadecimal equivalent followed by the number of zeros (0) 
that corresponds to the integer column minus one. 


Subtract the table decimal value from the decimal number to be 
converted. 


Repeat steps 1-3 until the subtraction balance equals zero (0). Add the 
hexadecimal equivalents to obtain the hexadecimal value. 


Octal / Hexadecimal /Decimal Conversion 


Example: 


22;466 (19) = ?(16) 
20,480 = 5000 22 +466 
1,792 = 700 -20,480 
192 = GO" ‘#eces=a5 
2 = 2 1,986 
een ---- - 1,792 
22,466 = S7C2  -------- 
194 
- 192 
Oo 
B.5 Hexadecimal Integer Columns 
8 7 6 5 4 3 2 1 
HEX DEC HEX DEC HEX DEC HEX DEC HEX DEC HEX DEC HEX DEC HEX DEC 
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 
1 268,435,456 1 16.777.216 1 1,048,576 1 65,536 1 4,096 1 256 1 16 1 1 
2 536,870,912 2 33,554,432 2 2,097,152 2 131,072 2 8,192 2 512 2 32 2 2 
3 805,306,368 3 50.331,648 3 3.145.728 3 196,608 3 12,288 93 768 3 48 3 3 
4 1,073,741,824 4 67,108.864 4 4,194,304 4 262,144 4 16,384 4 1,024 4 64 4 4 
5 1,342,177,280 5 83,886,080 5 5,242,880 5 327,680 5 20,480 5 1,280 5 80 5 5 
6 1,610,612,736 6 100,663,296 6 6.291.456 6 393,216 6 24,576 6 1,536 6 96 6 6 
7 1,879,048,192 z 117,440,512 7 7,340,032 7 458,752 7 28,672 t 1,792 i 112 7 Hf 
8 2,147,483,643 8 134,217,728 8 8,338,608 8 524,288 8 32,768 8 2,048 8 128 8 8 
2 2,415,919,104 9 150,994,944 9 9,437,184 9 589,824 9 36,864 9 2,304 9 144 9 9 
A 2,684,354,560 A 167,772,160 A 10,485,760 A 655,360 A 40,960 A 2,560 A 160 A 10 
B 2,952,790,016 B 184,549,376 B 11,534,336 B 720,896 B 45,056 B 2,916 B 176 B 11 
Cc 3,221,225,472 Cc 201,326,592 Cc 12,582,912 Cc 786,432 C 49,152 Cc 3,072 C 192 C 12 
D 3,489,660,928 D 218,103,808 D 13,631,488 D 851,968 D 53,248 D 3,328 D 208 D 13 
E 3,758,096,384 E 234,881,024 E 14,680,064 E 917,504 E 57,344 E 3,584 E 224 E 14 
F 4,026,531,840 i 251,658,240 F 15,728,640 F 983,040 F 61,440 F 3,840 F 240 F 15 


Ba ar a ee ee 


BYTE BYTE BYTE BYTE 


WORD WORD 


LONGWORD 


Octal / Hexadecimal / Decimal Conversion B-3 


Cc 


Appendix C 
The ASCIl Character Set Collating Sequence 


ASCII 
Character 


Hexadecimal 
Number 


ASCII 
8-Bit 
Octal 


Decimal 


oO wonnaw# ,—_ wo Wd 


Do wo OS WH WH WH WH HD NH KF KF FY Fe KF KF Ee 
Nanna fF Ww NOHO KFK§ CO HO WON DA F&F WO HO KF CO 


ASCII 
Character 


Ny oa fF WO NH KF CO 


ASCII 


Hexadecimal 8-Bit 


Number 


Octal Decimal 





(continued on next page) 
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ASCII ASCII 
ASCII Hexadecimal 8-Bit ASCII Hexadecimal 8-Bit 
Character Number Octal Decimal Character Number Octal Decimal 


zToOo7 POA Dw PY 


J 
K 
L 
M 
N 
O 
P 
Q 
R 
S) 
T 
U 
V 
Ww 
X 
Y 
Zz 


aol 





C-2 The ASCII Character Set Collating Sequence 


Ss Appendix D 
Data Types 


The data type refers to the way bits are grouped and interpreted. In refer- 
Cc ence to the processor instructions, the data type of an operand identifies the 
size of the operand and the significance of the bits in the operand. 


VAX-11 SORT/MERGE uses the following data types 
e Integer and Floating Point Data Types 


Binary (1, 2, 4, and 8—byte) 
F__Floating 


D__Floating 
Cc G__Floating 
H__Floating 

e Character String Data Type 

e Numeric String Data Types 


Trailing Overpunched Decimal String 
Leading Overpunched Decimal String 
Zoned Decimal String 

Leading Separate Decimal String 
Trailing Separate Decimal String 


e Packed Decimal String Data Type 


Figure D-1 summarizes the relationship of these data types. 


1-BYTE 2-BYTE 
(BYTE) (WORD) 


Figure D-1: VAX-11 SORT/MERGE Data Types 


INTEGER FLOATING POINT CHARACTER NUMERIC PACKED 


BINARY: STRING (DECIMAL) DECIMAL 
SIGNED, UNSIGNED 


4-BYTE 8-BYTE FFLOATING D FLOATING GFLOATING HFLOATING 
(LONGWORD) (QUADWORD) 


STRING 


OVERPUNCHED SEPARATE 


me 


TRAILING LEADING ZONED LEADING TRAILING 


D.1 Integer and Floating Point Data Types 


In the following discussion of integer and floating data types, the address of 
the datum in memory is the address of the byte of the datum with the 
lowest address. When depicted, this lowest byte is shown on the right and 
in discussions this is what is meant when the word “right” is used. 


D.1.1 Integer Data (Binary) 


VAX—11 SORT/MERGE uses integer data types of 8-, 16-, 32-, and 64-bit 
sizes. They are termed byte, word, longword, and quadword integers respec- 
tively. The integer data types are stored in memory in a binary format and 
can be treated as either signed or unsigned quantities. In the case of signed 
quantities, the integer is represented in two’s complement form. This 
means that positive numbers have a zero most significant bit (MSB) and 
the representation of a negative number is one greater than the bit-by-bit 
complement of its positive counterpart. Thus the MSB is always zero for 
positive values and one for negative values. When treated as unsigned 
quantities, integers extend upward from 0. 


One-Byte Binary (Byte) 


A byte is eight contiguous bits starting on an addressable byte boundary. 
The bits are numbered from the right 0 through 7: 


7 0 


D-2 Data Types 


A byte is specified by its address A. When interpreted as a signed quantity, 
a byte is a two’s complement integer with bits increasing in significance 
from 0 through 6, and with bit 7 designating the sign. The value of the 
integer is in the range —128 through 127. For the purposes of addition, 
subtraction, and comparison, VAX-—11 instructions also provide direct 
support for the interpretation of a byte as an unsigned integer with bits 
increasing in significance from 0 through 7. The value of the unsigned 
integer is in the range 0 through 255. 


Two-Byte Binary (Word) 


A word is two contiguous bytes starting on an arbitrary byte boundary. The 
bits are numbered from the right 0 through 15: 


15 0 


A word is specified by its address A, the address of the byte containing bit 
0. When interpreted as a signed quantity, a word is a two’s complement 
integer with bits increasing in significance from 0 through 14, and with bit 
15 designating the sign. The value of the integer is in the range —32,768 
through 32,767. For the purposes of addition, subtraction, and comparison, 
VAX-11 instructions also provide direct support for the interpretation of a 
word as an unsigned integer with bits increasing in significance from 0 
through 15. The value of the unsigned integer is in the range 0 through 
65,535. 


Four-Byte Binary (Longword) 


A longword is four contiguous bytes starting on an arbitrary byte bound- 
ary. The bits are numbered from the right 0 through 31: 


31 0 


A longword is specified by its address A, the address of the byte containing 
bit 0. When interpreted as a signed integer, a longword is a two’s comple- 
ment integer with bits increasing in significance from 0 through 30, and 
with bit 31 designating the sign. The value of the integer is in the range 
—2,147,483,648 through 2,147,483,647. For addition, subtraction, and com- 
parison, VAX—11 instructions also provide direct support for the interpreta- 
tion of a longword as an unsigned integer with bits increasing in signifi- 
cance from 0 through 31. The value of the unsigned integer is in the range 
0 through 4,294,967 ,295. 


Note that the longword format is different from the longword format 
defined by the PDP-11 FP-11. In that format, bits increase in significance 
from 16 through 31 and 0 through 14. Bit 15 is the sign bit. Most DIGITAL 
software, and in particular PDP-11 FORTRAN and COBOL, use the 
VAX-11 longword format. 
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Eight-Byte Binary (Quadword) 


A quadword is eight contiguous bytes starting on an arbitrary byte bound- 
ary. The bits are numbered from the right 0 through 63: 


31 0 


63 32 


A quadword is specified by its address A, the address of the byte containing 
bit 0. When interpreted as a signed integer, a quadword is a two’s comple- 
ment integer with bits increasing in significance from 0 through 62, and 
with bit 63 designating the sign. The value of the integer is in the range 
—2**63 to 2**63-1. 


D.1.2 Floating Point Data 


The floating point data types are used to represent approximations to quan- 
tities using a scientific notation consisting of a sign, the exponent of a 
power of two, and a fraction between .5 (inclusive) and 1.0 (exclusive). The 
value of a floating point number is the sign applied to the fractional part 
multiplied by two raised to the power specified by the exponent part. 
VAX-11 SORT/MERGE uses floating point data types of 32-, 64-, and 
128—-bit sizes. 


F__Floating 


An F__floating datum is four contiguous bytes starting on an arbitrary byte 
boundary. The bits are labelled from the right 0 through 31. 





15 14 76 0 
fraction At+2 






31 16 


An F__floating datum is specified by its address A, the address of the byte 
containing bit 0. The form of an F_floating datum is sign magnitude with 
bit 15 the sign bit, bits 14:7 an excess 128 binary exponent, and bits 6:0 and 
31:16 a normalized 24-bit fraction with the redundant most significant 
fraction bit not represented. Within the fraction, bits increase in signifi- 
cance from 16 through 31 and 0 through 6. The 8-bit exponent field encodes 
the values 0 through 255. An exponent value of 0, together with a sign bit 
of 0, is taken to indicate that the F_floating datum has a value of 0. 
Exponent values of 1 through 255 indicate true binary exponents of —127 
through +127. An exponent value of 0, together with a sign bit of 1, is 
taken as reserved. Floating point instructions processing a reserved oper- 
and take a reserved operand fault. The magnitude of an F__floating datum 
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2 


2 


is in the approximate range .29*10**—38 through 1.7*10**38. The precision 
of an F__floating datum is approximately one part in 2**23, that is, typi- 
cally 7 decimal digits. 


D_Floating 


The D__floating datum is eight contiguous bytes starting on an arbitrary 
byte boundary. The bits are labelled from the right 0 through 63: 















15 14 76 0 


63 48 

A D__floating datum is specified by its address A, the address of the byte 
containing bit 0. The form of a D_floating datum is identical to the 
F__floating datum except for an additional 32 low significance fraction bits. 
Within the fraction, bits increase in significance from 48 through 63, 32 
through 47, 16 through 31, and 0 through 6. The exponent conventions and 
approximate range of values are the same for both D_floating and 
F__floating. The precision of a D_floating datum is approximately one 
part in 2**55, that is, typically 16 decimal digits. 


G__Floating 


A G__floating datum is eight contiguous bytes starting on an arbitrary byte 
boundary. The bits are labelled from the right 0 through 63: 


15 14 43 0 










A+6 


63 48 


A G_floating datum is specified by its address A, the address of the byte 
containing bit 0. The form of a G_floating datum is sign magnitude with 
bit 15 the sign bit, bits 14:4 an excess 1024 binary exponent, and bits 3:0 
and 63:16 a normalized 53-bit fraction with the redundant most significant 
fraction bit not represented. Within the fraction, bits increase in signifi- 
cance from 48 through 63, 32 through 47, 16 through 31, and 0 through 3. 
The 11-bit exponent field encodes the values 0 through 2047. An exponent 
value of 0 together with a sign bit of 0, is taken to indicate that the 
G__floating datum has a value of 0. Exponent values of 1 through 2047 
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indicate true binary exponents of —1023 through +1023. An exponent 
value of 0, together with a sign bit of 1, is taken as reserved. Floating point 
instructions processing a reserved operand take a reserved operand fault. 
The value of a G_floating datum is in the approximate range .56*10**—308 
through .9*10**308. The precision of a G__floating datum is approximately 
one part in 2**52, that is, typically 15 decimal digits. 


H_Floating 


An H__floating datum is 16 contiguous bytes starting on an arbitrary byte 
boundary. The bits are labelled from the right 0 through 127: 





15 14 0 
127 112 


An H_floating datum is specified by its address A, the address of the byte 
containing bit 0. The form of an H__floating datum is sign magnitude with 
bit 15 the sign bit, bits 14:0 an excess 16384 binary exponent, and bits 
127:16 a normalized 113-bit fraction with the redundant most significant 
fraction bit not represented. Within the fraction, bits increase in signifi- 
cance from 112 through 127, 96 through 111, 80 through 95, 64 through 79, 
48 through 63, 32 through 47, and 16 through 31. The 15-bit exponent field 
encodes the values 0 through 32767. An exponent value of 0, together with 
a sign bit of 0, is taken to indicate that the H__floating datum has a value 
of 0. Exponent values of 1 through 32767 indicate true binary exponents of 
—16383 through + 16383. An exponent value of 0, together with a sign bit of 
1, is taken as reserved. Floating point instructions processing a reserved 
operand take a reserved operand fault. The value of an H__floating datum 
is in the approximate range .84*10**—4932 through .59*10**4932. The pre- 
cision of an H_floating datum is approximately one part in 2**112, that is, 
typically 33 decimal digits. 


D.2 Character String Data Type 


The character string is a data type used to represent strings of characters 
such as names, data records, or text. 


D-6 Data Types 


A character string is a contiguous sequence of bytes in memory. A charac- 
ter string is specified by two attributes: the address A of the first byte of the 
string, and the length L of the string in bytes. Thus the format of a charac- 
ter string is: 


7 0 


Gea 


7 0 


The address of a string specifies the first character of a string. For example, 
“XYZ” is represented: 


7 0 





The length L of a string is in the range 0 through 65,535. 


D.3 Numeric String (Decimal) Data Types 


The numeric string data types are used to represent fixed scaled quantities 
in a form close to their external representation. For programs that are 
input/output intensive rather than computation intensive, this presenta- 
tion is frequently more efficient. The decimal form also provides greater 
precision than floating point and greater range than integer. There are two 
forms of decimal data on VAX~11: (1) the decimal string data types in 
which each decimal digit occupies one byte, and (2) a more compact form 
(discussed in the next section) in which two decimal digits are packed into 
one byte. These are termed numeric and packed decimal strings respec- 
tively. Because the numeric string form must represent many external data 
arrangements exactly, it can be specified in several forms. Two significant 
distinguishing characteristics are: (1) whether the sign appears before the 
first digit or after the last digit, and (2) whether the sign is superimposed 
on the digit or separated from it. 


D.3.1 Overpunched Decimal Strings (Trailing, Zoned, Leading) 


A decimal string is a contiguous sequence of bytes in memory. The string is 
specified by two attributes: the address A of the first byte (most significant 
digit) of the string, and the length L of the string in bytes. 
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All bytes of a zoned or trailing overpunched decimal string, except the least 
significant digit byte, must contain an ASCII decimal digit character (0-9). 
For a leading overpunched numeric string, all bytes except the most signifi- 
cant digit byte must contain an ASCII decimal digit character (0-9). The 
representation for these digits is: 


digit decimal hex ASCII character 


0 48 30 0 
1 49 31 1 
2 50 32 2 
3 51 33 3 
4 52 34 4 
5 53 35 5 
6 54 36 6 
7 55 37 7 
8 56 38 8 
9 57 39 9 


The remaining byte represents an encoding of both the remaining digit and 
the sign of the decimal string. Thus, for zoned or trailing overpunched, the 
highest addressed byte represents an encoding of both the least significant 
digit and the sign of the numeric string. For leading overpunched, the 
lowest addressed byte represents an encoding of both the most significant 
digit and the sign of the numeric string. The VAX-11 numeric string 
instructions support any encoding; however, there are preferred encodings 
used by DIGITAL software. These include (1) zoned numeric, (2) trailing 
overpunched numeric, and (3) leading separate numeric. Because the over- 
punch format has been used by compilers of many manufacturers over 
many years, and because various card encodings are used, several varia- 
tions in overpunch format have evolved. Typically, these alternate forms 
are accepted on input. The valid representations of the digit and sign in 
these formats is: 






Zoned Numeric Format Overpunch Format 





ASCII char. 


digit decimal hex norm alt. 

0 0 123 7B { Ol? 
1 1 65 41 A 1 
2 2 66 42 B 2 
3 3 67 43 Cc 3 
4 4 68 44 D 4 
5 5 69 45 E 5 
6 6 70 46 F 6 
7 q 71 47 ._ G 7 
8 8 72 48 H 8 
9 9 73 49 I 9 

~—0 p 125 7D } }:! 

-1 q 74 4A J 

—2 r 75 4B K 

-3 s 76 4C L 

4 t 77 4D M 

—-5 u 78 4E N 

-6 Vv 79 4F O 

-7 Ww 80 50 P 

-8 x 81 51 Q 

-9 y 82 52 R 
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The length L of an overpunched numeric string must be in the range 0 to 31 
(0 to 31 digits). The value of a 0 length string is identically 0. 


The address A of the string specifies the byte of the string containing the 
most significant digit. Digits of decreasing significance are assigned to 
increasing addresses. Thus “123” is represented: 


Zoned Format 





And “—123” is represented: 


Zoned Format 
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Trailing Overpunch Format 





D.3.2 Leading Separate and Trailing Separate Decimal Strings 


A decimal string is a contiguous sequence of bytes in memory. The string is 
specified by two attributes: the address A of the first byte of the string, and 
a length L that is the length of the string in digits and NOT the length of 
the string in bytes. In a leading separate numeric string, the first byte 
contains the sign character; in a trailing separate number string, the last 
byte contains the sign character. The number of bytes in a leading or trail- 
ing separate numeric string is L+1. 


The sign of a leading separate or trailing separate decimal string is stored 
in a separate byte. Valid sign bytes are: 


sign decimal hex ASCII character 
+ 43 2B + 
+ 32 20 <blank> 
- 45 2D - 


The preferred representation for “+” is ASCII “+”. All subsequent bytes 
contain an ASCII digit character: 


digit decimal hex ASCII character 


0 48 30 0 
1 49 31 1 
2 50 32 2 
3 51 33 3 
4 52 34 4 
5 53 35 5 
6 54 36 6 
7 55 37 7 
8 56 38 8 
9 57 39 9 


The length L of a leading or trailing separate numeric string must be in the 
range 0 to 31 (0 to 31 digits). The value of a 0 length string is identically 0. 
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The address A of the leading separate decimal string specifies the byte of 
the string containing the sign. The address A of the trailing separate deci- 
mal string specifies the byte of the string containing the high order digit. 
Digits of decreasing significance are assigned to bytes of increasing 
addresses. Thus “+ 123” is: 


Leading Separate Format 





And “—123” is: 


Leading Separate Format 


‘A+2 


A+3 


A+2 





‘A+3 
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D.4 Packed Decimal String 


D-12 


A packed decimal string is a contiguous sequence of bytes in memory. A 
packed decimal string is specified by two attributes: the address A of the 
first byte of the string and a length L that is the number of digits in the 
string and NOT the length of the string in bytes. The bytes of a packed 
decimal string are divided into two 4—bit fields (nibbles) that must contain 
decimal digits except the low nibble (bits 3:0) of the last (highest addressed) 
byte, which must contain a sign. The representation for the digits and 
sign is: 


digit or sign decimal hex 

0 0 0 

1 1 1 

2 2 2 

3 3 3 

4 4 4 

5 5 5 

6 6 6 

7 7 7 

8 8 8 

9 9 9 

+ 10, 12, 14, or 15 A, C, E, or F 
- 11 or 13 B or D 


The preferred sign representation is 12 for “+” and 13 for “—’. The length L 
is the number of digits in the packed decimal string (not counting the sign) 
and must be in the range 0 through 31. When the number of digits is odd, 
the digits and the sign fit in L/2 (integer part only)+1 bytes. When the 
number of digits is even, it is required that an extra “0” digit appear in the 
high nibble (bits 7:4) of the first byte of the string. Again, the length in 
bytes of the string is L/2+1. 


The address A of the string specifies the byte of the string containing the 
most significant digit in its high nibble. Digits of decreasing significance 
are assigned to increasing byte addresses and from high nibble to low nib- 
ble within a byte. Thus “+ 123” has length 3 and is represented: 


7 43 0 





And “~12” has length 2 and is represented: 
7 43 0 
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Glossary 


Address 


A name, label or number that identifies a location in memory where data is stored. 


ASCII 


Acronym for American Standard Code for Information Interchange; a set of 128 
eight-bit characters used for standard representation of data. 


Batch Processing 


A mode of processing in which all commands to be executed by the operating 
system (and, optionally, data to be used as input to the commands) are placed ina 
file or punched onto cards and submitted to the system for execution. 


Bit Flag 
See Flag. 


Block 


The smallest addressable unit of data that the specified device can transfer in an 
I/O operation (512 contiguous bytes for most disk devices). , 


Bucket 


A storage structure of 1 to 32 blocks used to store and transfer blocks of data in 
files with a relative file organization. 


Buffer 


An internal memory area used for temporary storage of data during input or 
output operations. 


Byte 
The smallest addressable unit of information; eight contiguous bits that are oper- 
ated on by the computer as a unit. 


Glossary-1 


Call 


To transfer control to a specified routine. 


Character 


A single printable letter, number, or symbol represented by one byte. 


Collating Sequence 


An order assigned to the characters of a character set (for example, ASCII and 
EBCDIC) used for sequencing purposes. 


Command 


An instruction, generally an English word, typed by the user at a terminal or 
included in a command file. A command requests the software monitoring a termi- 
nal or reading a command file to perform some pre-defined activity. For example, 
typing the SORT command requests the system to invoke the SORT utility. An 
entire command can consist of the command name, qualifiers, and parameters. 


Command Procedure 


A file containing a sequence of commands to be executed by the operating system. 


The command procedure can be submitted for execution at the terminal or as a 
batch job. 


Contiguous Blocks 


Physically adjacent and/or consecutively numbered blocks of data. 


Control Bytes 
See Variable with Fixed-Length Control (VFC) Record Format. 


Data Type 


An interpretation applied to a series of bits, based on the way in which the bits are 
grouped. The data type of an operand identifies its size and the significance of the 
bits in the operand. 


Default 


An assumed value supplied by the system when the user does not specify a com- 
mand qualifier. 


Descriptor 


A quadword data structure used in calling sequences for passing character strings. 
The first word of the quadword contains the length of the character string. The 


second word can contain type information. The remaining longword contains the 
address of the string. 


Glossary-2 


Digit 


One symbol in a numbering system. 


EBCDIC 


Acronym for Extended Binary Coded Decimal Interchange Code; a set of eight-bit 
characters used for representing data. 


Field 


A logically distinguishable byte or group of bytes within a record, usually a unit of 
information. 


File 
An organized collection of records maintained in an accessible storage area, such 
as disk or tape. The user can manipulate a file as a unit. 


File Organization 


The particular VAX-11 RMS file structure used to arrange the data constituting 
a file on a mass storage medium. See Sequential, Relative, and Indexed- 
Sequential File Organizations. 


File Specification 


A unique name for a file on a mass storage medium. It identifies the node, the 
device, the directory name, the file name, and the version number under which a 
file is stored. 


Fixed-Length Record Format 


A file format in which all records have the same length. 


Flag 


A bit that can be set to invoke the execution of some sequence of instructions; 
frequently, an indicator used to tell some later part of a program that a certain . 
condition occurred earlier. 


Floating Point Data 


A method for compact storage of very large and very small numbers. The number 
is represented in two parts, a fraction and an exponent. 


Indexed-Sequential File Organization 


A file organization in which records are arranged according to a primary key 
specified by the user. In addition to the records, the file contains the primary key 
index and (optionally) one.or more alternate key indexes. RMS places the records 
in order by the primary key index and maintains this sequence when new records 
are added. Records can be accessed sequentially by index key or randomly by 
alternate index key. 
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Input File 


The file containing the records you wish to sort or merge. 


Key 
The data field in a record that contains the information by which the user wants to 
arrange the records. 

Longword 
Four contiguous bytes (32 bits) starting on an addressable byte boundary. 

Merge 
A process which combines records into one sequenced file from two or more simi- 
larly sequenced files. 

Output File 


The file created by running SORT or MERGE. 


Packed Decimal 


A method for compact storage of a decimal number. Two digits are stored in each 
8-bit byte, taking advantage of the fact that only 4 bits are required to represent 
the numbers 0 through 9. The sign resides in the last byte of the low-order digit. 


Parameter 


Object of a command. A parameter can be a file specification, a keyword option, or 
a symbol value. 


Qualifier 


A portion of a command string that modifies a command verb or command param- 
eter. A qualifier follows the command verb or parameter to which it applies and is 
in the format: /qualifier[ = option]. 


Record 
A set of related data treated as a unit; usually, one unit in a file. 


Record Format 


The way a record physically appears on the recording surface of the storage 
medium. See Fixed-Length, Variable-Length, and Variable with Fixed- 
Length Control Record Formats. 


Record’s File Address (RFA) 


The unique address of a record in a disk file that allows records to be accessed 
randomly regardless of file organization. 
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Relative File Organization 


A file organization in which the file contains fixed length record cells. Each cell is 
assigned a consecutive number representing its position relative to the beginning 
of the file. Records within each cell can be as big as or smaller than the cell. 
Relative file organization permits sequential record access, random record access 
by record number, and random record access by record’s file address. 


RMS 
VAX-11 Record Management Services; the file and record access subsystem of the 
VAX/VMS operating system. VAX-11 RMS is a set of software routines in the 
operating system that maintains, organizes, and processes data, and allows access 
to files and records. 

Routine 
A set of sequenced instructions that causes a computer to perform particular 
functions. 


Sequential File Organization 


A file organization in which records are arranged in the sequence they were 
originally written. The records can be fixed length or variable length. Sequential 
file organization permits sequential record access and random access by record’s 
file address. Sequential file organization with fixed length records also permits 
random access by relative record number. 


Sort 
A process that arranges records in a prescribed sequence. 


Specification File 


A file of records that contain the SORT command qualifiers in prescribed posi- 
tions. A specification file must include one Header Record and as many Field 
Specification Records as there are keys in the sort. 


Status Code 
A longword value that indicates the success or failure of a specific function. 


Subroutine 


A subsidiary routine that executes when called by another program. A subroutine 
is often called repeatedly until a certain condition is met. 


Utility 
A program that provides a set of related general purpose functions. 


Variable-Length Record Format 
A file format in which records are not necessarily the same length. 
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Variable with Fixed-Length Control (VFC) Record Format 


A record format in which a fixed-length control area is prefixed to a variable- 
length record. This control area contains information about the record that may a | 


have no bearing on the contents of the record, for example, file line numbers 
and/or print format controls. 


Volume 


A mass storage medium such as a disk pack or reel of magnetic tape. 


Word 


Two contiguous bytes (16 bits) starting on an addressable byte boundary. 


Work File 

A collection of sorted records created during the sort operation and released when 

the sort is finished. ) 
Zoned Numeric Format 


A specific ASCII coded decimal data type where the number sign and the least 
significant digit are combined into a single hexadecimal code. 
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A 
ADDRESS, sort process subqualifier, 2-11, 
2-24 
Address sort 
reasons for selecting, 2-12 to 2-13 
specifying in file interface, 3-10 
/ALLOCATION, output file qualifier, 2-17, 
2-27 
Allocation of blocks, specifying 
in callable SORT/MERGE, 3-7 
with output file qualifier, 2-17, 2-27 
ASCENDING, key subqualifier, 2-11, 2-24 
Ascending, order of sort, 2-11, 2-24 
ASCII collating sequence 
character set, chart, C-1 to C-2 
specifying, 2-14, 2-25 


B 
BASIC, sample programs 
MERGE, 3-22 to 3-23 
SORT, 3-21 
Batch processing 
advantages of, 1-8 
creating command procedure, 1-8 
executing command procedure, 1-8 
explanation of, 1-8 to 1-9 
log file, 1-8 
SUBMIT command, 1-8 
Batch queue, assigning for optimization, 4-6 
BINARY, key subqualifier, 2-9, 2-23 
Binary data type 
description of, D-3 to D-4 
specifying, 2-9, 2-23 
BLISS-—32, sample program (SORT), 3—24 to 
3-30 
Block allocation, specifying 
in callable SORT/MERGE, 3-7 
with output file qualifier, 2-17, 2-27 
Block size (magnetic tape), specifying 
in callable SORT/MERGE, 3-7 
with format subqualifier, 2-16, 2-26 
BLOCK_SIZE, output file subqualifier 
for magnetic tape, 2-16, 2-26 
Bucket size, specifying 
in callable SORT /MERGE, 3-7 
with output file qualifier, 2-17, 2-27 
Bucket splitting, minimizing, 2-17 


/BUCKET_SIZE, output file qualifier, 2-17, 


2-27 
Buffer, key. See Key buffer 


Buffer, record. See Record buffer 
Buffered I/O count, 4—3 
Byte, description of, D-2 


Cc 
Callable MERGE, subroutines 
SOR$DO__MERGE, 3-19 
SOR$END__SORT, 3-14 
SORS$INIT__MERGE, 3-17 to 3-18 
SOR$PASS_FILES, 3-5 to 3-8 
SOR$RETURN_REC, 3-13 to 3-14 
summary chart, 3-20f 
Callable SORT, subroutines 
SOR$END__SORT, 3-14 
SORSINIT_SORT, 3-8 to 3-11 
SOR$PASS__FILES, 3-5 to 3-8 
SOR$RELEASE__REC, 3-12 
SOR$RETURN_REC, 3-13 to 3-14 
SOR$SORT__MERGE, 3-13 
summary chart, 3—20f 
Calling MERGE 
concepts of, 3-14 to 3-16 
file interface, 3-15 
record interface, 3-16 
subroutine functions, 3—15t 
subroutine order, 3-16f 
Calling SORT 
concepts of, 3-3 to 3—4 
file interface, 3-4 
record interface, 3—4 
subroutine functions, 3—3t 
subroutine order, 3-—5f 
Calls to MERGE. See Callable MERGE 
Calls to SORT. See Callable SORT 
CHARACTER, key subqualifier, 2-9, 2—23 
Character data type. specifying, 2-9, 2-23 
Character string, description of, D-6 to D-7 
/CHECK__SEQUENCE, MERGE command 
qualifier, 2-22, 2-25 
COBOL, merging in, 3-19 
COBOL, sorting in, 3-19 
Collating sequence 
ASCII, 2-14, 2-25, C-1 to C-2 
EBCDIC, 2-14, 2-22, 2-25 
EBCDIC, in callable MERGE, 3-17 
EBCDIC, in callable SORT, 3-11 
/ COLLATING_SEQUENCE 
MERGE command qualifier, 2-22, 2-25 
SORT command qualifier, 2-14, 2-25 
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Comparison routine address, specifying 
in callable MERGE, 3-17 
in callable SORT, 3-10 to 3-11 


Compatibility mode, invoking SORT-11, 2-14, 


2-25 
/CONTIGUOUS, output file qualifier, 2-17, 
2-27. See also /ALLOCATION 


CONTROLLED, output file subqualifier, 2-16, 


2-26. See also SIZE 
CPU time, in SORT statistics, 4-4 


D 
Data type(s) 
codes for callable SORT/MERGE, 3-9t 
definition of, D-1 
list of, used by SORT/MERGE, D-1 
Data types, description of 
binary, D—2 to D-4 
character, D—6 to D-7 
decimal, D-7 to D-11 
D__floating, D-5 
floating point, D—4 to D-6 
F__floating, D-4 to D-5 
G_floating, D-5 to D-6 
H__floating, D-6 
integer, D-2 to D—4 
packed decimal, D-12 
zoned, D-7 to D-10 
Data types, specifying 
binary, 2-9, 2-23 
character, 2—9, 2-23 
decimal, 2-9, 2~24 


D__FLOATING, 2-9, 2-23 
F__FLOATING, 2-9, 2-23 
G_FLOATING, 2-9, 2~23 
H_FLOATING, 2-9, 2-23 
packed decimal, 2-9, 2-23 


zoned, 2-9, 2-23 
DECIMAL, key subqualifier, 2-9, 2-23 
Decimal conversion 

to hexadecimal, B—2 to B-3 

to octal, B—1 
Decimal data type 

description of, D—7 to D-11 

specifying, 2-9, 2-24 
DESCENDING, key subqualifier, 2-11, 2-24 
Descending, order of sort, 2-11, 2-24 
Direct I/O count, 4-3 
D__FLOATING, key subqualifier, 2-9, 2-23 
D__floating datum, description of, D-5 


E 
EBCDIC collating sequence, specifying 
in callable MERGE, 3-17 
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EBCDIC collating sequence, specifying (Cont.) 
in callable SORT, 3-11 
with command qualifier, 2-14, 2-22, 2-25 
Elapsed time, in SORT statistics, 4-4 
Error conditions, categories of, A-1 
Error messages 
command interpreter, format of, A-1 to A-2 
RMS, interpretation of, A-8 
SORT/MERGE, corrective action for, 
A-2 to A-8 
SORT/MERGE, explanation of, A-2 to A-8 


F 
Field specification record, in specification file, 
2-29 
File interface 
advantages of, 3-2 
calls to MERGE, 3-15 
calls to SORT, 3-4 
File interface, sample programs 
FORTRAN (SORT), 3-31 
MACRO (SORT), 3-35 to 3-36 
PL/I (SORT), 3-45 to 3-46 
File organization (output), specifying 
in callable SORT/MERGE, 3-6 
with qualifiers, 2-17, 2-27 
File qualifier(s) 
input. See Input file qualifier 
output. See Output file qualifiers 
FILE_SIZE, input file subqualifier, 2—2, 
2-21, 2-26 
FIXED, output file subqualifier, 2-16, 2-26 
Fixed field format 
sample specification file, 2-30 
sort instructions in, 2-28 
Fixed-iength records, specifying, 2-16, 2-26 
Floating point data types 
description of, D—4 to D-6 
subqualifiers for, 2-9, 2-23 
/FORMAT 
input file qualifier, 2-2, 2-5, 2-21, 
2-25 to 2-26 
output file qualifier, 2-16, 2-26 
output file, default, 2-16. 
Format (output file), changing, 2-16, 2-26, 
3-7 
FORTRAN, sample programs 
MERGE, 3-32 to 3-34 
SORT, 3-31 
Free field format 
sample specification file, 2-30 
sort instructions in, 2-28 
F__FLOATING, key subqualifier, 2-9, 2-23 
F_floating datum, description of, D-4 to D-5 


G 
G__FLOATING, key subqualifier, 2-9, 2-23 
G__floating datum, description of, D-5 to D-6 


H 
Header record, in specification file, 2-28 to 
2-29 

Hexadecimal 

conversion to decimal, B-2 

integer columns, B-3 
H__FLOATING, key subqualifier, 2-9, 2-23 
H__floating datum, description of, D-6 


1/O 
interfaces, 3-2 
optimization, 4-3 to 4—4 
INDEX, sort process subqualifier, 2-11, 2—24 
Index sort 
reasons for selecting, 2-12 to 2-13 
specifying in file interface, 3-10 
/INDEXED__SEQUENTIAL, output file 
qualifier, 2-17, 2-27 
Initial runs, number of in work file, 4-4 
Input file parameter, description of 
MERGE, 1-6, 1-7, 2-18 
SORT, 1-4, 1-5, 2-1 to 2-2, 2-5 
Input file qualifier 
/FORMAT, 2-2, 2-5, 2-21, 2-25 to 2-26 
summary chart (MERGE), 2—20f 
summary chart (SORT), 2—4f 
Input file subqualifiers 
FILE__SIZE, 2-2, 2-21, 2-26 
RECORD_SIZE, 2-2, 2-21, 2-25 
Input file(s) 
descriptor, in callable SORT/MERGE, 3-6 
multiple, requirements of for SORT, 2-2 
size, specifying in callable SORT, 3-10 
Input routine address, in callable MERGE, 
3-17 to 3-18 
Integer data types, description of, D-2 to D-4 
Interfaces, I/O, 3-2 
Internal operations of SORT, 4-1 to 4-3 


K 
/KEY 
MERGE command qualifier, 2-21, 2-23 to 
2-24 
SORT command qualifier, 2—5 to 2-11, 
2-23 to 2-24 
Key buffer 
defining keys in, 3-8 
sample, 3-9 


Key buffer address, specifying 
in callable MERGE, 3-17 
in callable SORT, 3-8 to 3-10 
Key field(s) 
multiple, priority of, 2-5 
number allowed, 1—4 
specifying position of, 2-10, 2-23 
specifying size of, 2-10, 2-23 
Key options, specifying, summary chart, 2-8f 
Key order, 2-11, 2-24 
Key size, specifying 
in bytes, 2-10, 2-23 
for callable SORT, 3-10 
in characters, 2—10, 2—23 
in digits, 2-10, 2-23 
for packed decimal, 2-10 
Key subqualifiers 
ASCENDING, 2-11, 2-24 
BINARY, 2-9, 2-23 
CHARACTER, 2-9, 2-23 
DECIMAL, 2-9, 2-23 
DESCENDING, 2-11, 2-24 
D__FLOATING, 2-9, 2-23 
F_FLOATING, 2-9, 2-23 
G__FLOATING, 2-9, 2-23 
H__FLOATING, 2--9, 2-23 
information from, 2—5 
LEADING_SIGN, 2-9, 2-24 
NUMBER, 2-11, 2-24 
OVERPUNCHED__SIGN, 2-10, 2-24 
PACKED__DECIMAL, 2-9, 2—23 
POSITION, 1-4, 2-10, 2-23 
requirements of (MERGE), 1—7 
requirements of (SORT), 1-4 to 1-5 
SEPARATE_SIGN, 2-10, 2-24 
SIGNED, 2-9, 2-23 
SIZE, 1-4, 2-10, 2-23 
TRAILING_SIGN, 2-9, 2-24 
UNSIGNED, 2-9, 2—23 
ZONED, 2-9, 2-23 
Keys, multiple, specifying order of, 2-11, 2-24 


L 
Languages, list of, calling SORT/MERGE, 3-1 
Leading sign decimal data 
overpunched, description of, D—7 to D—10 
separate, description of, D-10 to D-11 
specifying, 2-9, 2-24 
LEADING_SIGN, key subqualifier, 2-9, 2-24 
/LOAD__FILL, output file (indexed) qualifier, 
2-17, 2-27 
Log file, from batch job, 1-8 
Longest record length (LRL) 
in callable MERGE, specifying, 3-17 
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Longest record length (LRL) (Cont.) 
in callable SORT, specifying, 3-10 
format (input) subqualifier for, 2-2, 2-25 
format (output) subqualifiers for, 2-16, 2-26 
in SORT statistics, 4-4 

Longword, description of, D-3 


M 
MACRO, sample program (SORT), 3-35 to 
3-36 
Merge 
options, specifying in callable MERGE, 3-17 
order, specifying in callable MERGE, 3-17 
passes, number of in work file, 4—4 
MERGE, callable. See Callable MERGE 
MERGE, calling, concepts of, 3-14 to 3-16 
MERGE command, format, described, 1-6, 
2-18 
MERGE command qualifiers 
/CHECK_SEQUENCE, 2-22, 2-25 
/COLLATING__SEQUENCE, 2-22, 2-25 
/KEY, 2-21, 2-23 to 2-24 
rules for specifying, 1-7 
summary chart, 2—19f 
Merge operation, sample, 1-6 to 1-7 
MERGE subroutines 
calling order of, 3-16f 
description of each. See Callable MERGE 
functions of, 3-15t 
overview of, 3-14 to 3-16 
Modified page writer cluster, changing value 
of, 4-7 
Multi block count, I/O optimization, 4-3 
Multi buffer count, I/O optimization, 4-3 
Multiple 
input files, 2-2 
keys, priority of, 2—5 


N 
NUMBER, key subqualifier, 2-11, 2-24 
Numeric string (decimal) data types 
description of, D-7 to D-11 
specifying, 2-9, 2-24 


oO 

Octal conversion, to decimal, B-1 
Optimizing SORT, 4—5 to 4-7 
Order of key, 2-11, 2-24 
Order of the merge, I/O optimization, 4-4 
Output file organization, specifying 

in callable SORT/MERGE, 3-6 

with qualifiers, 2-17 
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Output file parameter, description of 
MERGE, 1-5, 1-6, 1-8, 2-22 
SORT, 1-4, 2-15 to 2-17 
Output file parameters, in callable 
SORT /MERGE, 3-6 to 3-8 
Output file qualifiers 
/ALLOCATION, 2-17, 2-27 
/BUCKET_SIZE, 2-17, 2-27 
/CONTIGUOUS, 2-17, 2-27 
/FORMAT, 2-16, 2-26 
/INDEXED__SEQUENTIAL, 2-17, 2-27. 
See also /OVERLAY 
/LOAD_FILL, 2-17, 2-27 
/OVERLAY, 2-17, 2-27 
/RELATIVE, 2-17, 2-27 
requirements of (MERGE), 2-22 
requirements of (SORT), 2-15 to 2-16 
/SEQUENTIAL, 2-17, 2-27 
summary chart (MERGE), 2—20f 
summary chart (SORT), 2—4f 
Output file subqualifiers 
BLOCK_SIZE, 2-16, 2-26 
CONTROLLED, 2-16, 2-26 
FIXED, 2-16, 2-26 
SIZE (VFC records), 2-16, 2-26 
VARIABLE, 2-16, 2-26 
/OVERLAY, output file qualifier, 2-17, 2-27 
OVERPUNCHED_SIGN, key subqualifier, 
2-10, 2-24 


P 
Packed decimal string, description of, D—12 
PACKED__DECIMAL, key subqualifier, 2-9, 
2-23 
Page faults, I/O optimization, 44 
PASCAL, sample programs 
MERGE, 3-41 to 3-44 
SORT, 3-37 to 3-40 
PL/I (SORT), sample programs, 3-45 to 3-48 
POSITION, key subqualifier, 1-4, 2-10, 2-23 
Powers of 2 and 16, B-2 
Process, selecting. See Sort process, selecting 
/PROCESS, SORT command qualifier. 2-11, 
2-24 
Process section count, setting for optimization, 
4-7 


Q 
Quadword, description of, D-4 
Qualifiers 
/ALLOCATION, 2-17, 2-27 
/BUCKET_SIZE, 2-17, 2-27 
/CHECK__SEQUENCE, 2-22, 2-25 


C 





Qualifiers (Cont.) ; 
/COLLATING_.SEQUENCE, 2-14, 2-22, 
2-25 
/CONTIGUOUS, 2-17, 2-27 
/FORMAT (input file), 2-2, 2-21, 
2-25 to 2-26 
/FORMAT (output file), 2-16, 2-26 
/INDEXED_SEQUENTIAL, 2-17, 2-27 
/KEY, 1-4, 1-7, 2-5 to 2-11, 2-21, 
2-23 to 2-24 
/LOAD__FILL, 2-17, 2-27 
/OVERLAY, 2-17, 2-27 
/PROCESS, 2-11 to 2-13, 2-24 
/RELATIVE, 2-17, 2-27 
/RSX11, 2-14, 2-25 
/SEQUENTIAL, 2-17, 2-27 
/SPECIFICATION, 2-14, 2-25 
/STABLE, 2-13, 2-24 
/STATISTICS, 2-14 
/WORK_FILES, 2-14, 2-25 


R 
RECORD, sort process subqualifier, 2-11, 2-24 
Record buffer, describing 
record released to SORT, 3-12 
sorted record, 3-13 to 3-14 
Record descriptor 
for released record, 3—12 
for sorted record, 3-13 to 3-14 
Record File Addresses (RFAs), 2-12 
Record format (output file), changing, 
2-16, 2-26, 3-7 
Record interface 
advantages of, 3—2 
calls to MERGE, 3-16 
calls to SORT, 3-4 
Record interface, sample programs 
BASIC (MERGE), 3-22 to 3-23 
BASIC (SORT), 3-21 
BLISS—32 (SORT), 3-24 to 3-30 
FORTRAN (MERGE), 3-32 to 3-34 
MACRO (SORT), 3-36 
PASCAL (MERGE), 3-41 to 3—44 
PASCAL (SORT), 3-37 to 3-40 
PL/I (SORT), 3-47 to 3-48 
Record size, of returned record, specifying, 
3-14 
Record sort 
reasons for selecting, 2-12 to 2-13 
specifying in callable interface, 3-10 
Records, fixed-length. See Fixed-length records 
Records, variable-length. See Variable-length 
records 


Records, VFC. See Variable with fixed-length 
control records 

RECORD__SIZE, input file subqualifier, 2-2, 
2-21, 2-25 

/RELATIVE, output file qualifier, 2-17, 2-27 

/RSX11, SORT command qualifier, 2-14, 
2-25 

Running SORT/MERGE, ways of, 1-1 


Ss 
SEPARATE_SIGN, key subqualifier, 2-10, 
2-24 
Sequence check, specifying in callable 
MERGE, 3-17 
/SEQUENTIAL, ouptut file qualifier, 2-17, 
2-27 
SIGNED, key subqualifier, 2-9, 2-23 
Signed binary data, specifying, 2-9, 2-23 
SIZE 
key subqualifier, 1-4, 2-10, 2-23 
output file subqualifier, VFC records, 2-16, 
2-26 
Size, specifying 
input file, 2-2, 2-21 
input file in callable SORT, 3-10 
key field, 2-10 to 2-11, 2-23 
record, 2—2, 2-21 
SOR$DO__MERGE, MERGE subroutine 
description of, 3-19 
status code returns, 3-19t 
SOR$SEND__SORT, SORT/MERGE subroutine 
description of, 3-14 
status code returns, 3—14t 
SOR$INIT_MERGE, MERGE subroutine 
description of, 3-17 to 3-18 
status code returns, 3-18t 
SORS$INIT__SORT, SORT subroutine 
data type codes, 3—9t 
description of, 3-8 to 3-11 
status code returns, 3-11t 
SOR$PASS__FILES, SORT / MERGE subroutine 
description of, 3-5 to 3-8 
status code returns, 3—8t 
SOR$RELEASE__REC, SORT subroutine 
description of, 3-12 
status code returns, 3—12t 
SOR$RETURN_REC, SORT /MERGE 
subroutine 
description of, 3-13 to 3-14 
status code returns, 3-14t 
SOR$SORT__MERGE, SORT subroutine 
description of, 3-13 
status code returns, 3-13t 
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SOR$V__EBCDIC, 3-11, 3-17 
SOR$V__SEQ__CHECK, 3-17 
SOR$V__STABLE, 3-11 
SORT, callable. See Callable SORT 
SORT, calling, concepts of, 3-3 to 3-4 
SORT-11, invoking, 2-14, 2-25 
SORT algorithm, 4-1 to 4-3 
SORT command, format, described, 1-3, 2-1 
SORT command qualifiers 
/COLLATING__SEQUENCE, 2-14, 2-25 
/KEY, 2-5 to 2-11, 2-23 to 2-24 
/PROCESS, 2-11, 2—24 
/RSX11, 2-14, 2-25 
rules for specifying, 1-4 
/SPECIFICATION, 2-14, 2—25 
/STABLE, 2-13, 2-24 
/STATISTICS, 2-14, 2-25, 4-3 
summary chart, 2—3f 
/WORK__FILES, 2-14, 2-25 
Sort operation, sample, 1—2 to 1-3, 1-4, 
2-6 to 2-7f 
Sort options, specifying in callable SORT, 
3-11 
Sort process 
default, 2-13 
in I/O interfaces, 3-10 
selecting, 2-11 to 2-13, 4-6 
subqualifiers, 2-11, 2-24 
SORT processes, summary, 2—12t 
SORT specifications form, 2—30f 
SORT statistics, 4-3 to 4-4 
SORT subroutines 
calling order of, 3-5f 
description of each. See Callable SORT 
functions of 3-3t 
overview of, 3-3 to 3-4 
Sort tree, explanation of, 4-2 
SORT /MERGE 
efficiency, 4-4 
environment designed for, 4—4 
/SPECIFICATION, SORT command qualifier, 
2-14, 2-25 
Specification file 
definition of, 2-14 
field specification record, 2—29 
header record, 2-28 to 2-29 
prompted, 2-31 
purpose of, 2-27 
record formats, 2—28 
record types, 2-28 
restrictions of, 2—27 
samples, 2-30 
specifying in SORT command, 2-31 
/STABLE, SORT command qualifier, 2-13, 
2-24 
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Stable sort, specifying in callable SORT, 3-11 
Statistics, SORT 
sample display, 4~3 
uses of, for optimization, 4-3 to 4-4 
/STATISTICS, SORT command qualifier, 
2-14, 2-25, 4-3 
Status code returns 
SOR$DO__MERGE, 3-19t 
SOR$END__SORT, 3-14t 
SOR$INIT__MERGE, 3-18t 
SOR$INIT__SORT, 3-11t 
SOR$PASS__FILES, 3-8t 
SOR$RELEASE__REC, 3-12t 
SOR$RETURN_REC, 3-14t 
SOR$SORT__MERGE, 3-13t 
Subroutines, MERGE. See Callable MERGE 
Subroutines, SORT. See Callable SORT 


t 
TAG, sort process subqualifier, 2-11, 2-24 
Tag sort 
reasons for selecting, 2-12 to 2-13 
specifying in file interface, 3-10 
Trailing sign decimal data 
overpunched, description of, D—-7 to D-10 
separate, description of, D-10 to D-11 
specifying, 2-9, 2-24 


TRAILING_SIGN, key subqualifier, 2-9, 2-24 


U 
UNSIGNED, key subqualifier, 2-9, 2-23 
Unsigned binary data, specifying, 2-9, 2-23 
User comparison routine 
MERGE, 3-17 
SORT, 3-10 


Vv 
VARIABLE, output file subqualifier, 2-16, 
2-26 
Variable-length records, specifying, 2-16, 
2-26 
Variable with fixed-length control records 
specifying, 2-16, 2-26 
Virtual memory, in SORT statistics, 4-4 
Virtual page count, setting for optimization, 
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W 
Word, description of, D-3 
Work files 
assigning to devices, 2-14, 4-5 
explanation of, 4—2 
specifying number of, 3-10 


Working set 
maximum used, 4~-3 
quota, 4-4 to 4-5, 4-6 
sort tree, 4-2 
/WORK__FILES, SORT command qualifier, 
cae 2-14, 2-25 





Z 
ZONED, key subqualifier, 2-9, 2—23 
Zoned decimal string, description of, D—7 to 
D-9 
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